TERMS  AND  CONDITIONS  OF  SALE  AND  LICENSE  OF  TANDY  COMPUTER  EQUIPMENT  AND 

SOFTWARE  PURCHASED  FROM  RADIO  ShACK  COMPANV-OWNED  COMPUTER  CENTERS,  RETAIL 

STORES  AND  RAOIO  SHACK  fRANCHISEES  OR  DEAcERS  AT  THEIR  AUTHORIZED  LOCATIONS 

USA  LIMITED  WARRANTY 

CUSTOMER  OBLIGATIONS 

A.  CUSTOMER  assumes  full  responsibility  thai  this  computet  hardware  purchased  (the  "Equipment"),  and  any 
copies  of  software  included  with  the  Equipment  or  licensed  separately  (the  "Software")  meets  the  specifications, 
capacty.  capao  it.es.  versatility  and  other  requirements  of  CUSTOMER. 

B.  CUSTOMER  assumes  full  responsibility  for  the  condition  and  effectiveness  of  the  operating  environment  in  which 
the  Equipment  and  Software  are  to  lunctor,  and  tor  its  installation. 

LIMITED  WARRANTIES  AND  CONDITIONS  OF  SALE 

A.  For  a  period  of  ninety  (90)  calendar  days  from  the  date  of  the  Radio  Shack  sales  document  received  upon 
purchase  of  the  Equipment  RADIO  SHACK  warrants  to  the  original  CUSTOMER  that  the  Equipment  and  the 
mediuT  upon  which  the  Software  is  stored  is  free  from  manufacturing  delects.  This  warranty  Is  only  applicable 
to  purchases  of  Tandy  Equipment  by  the  original  customer  from  Radio  Shack  company-owned  computer 
centers,  retail  stores,  and  Radio  Shack  franchisees  and  dealers  at  their  authorized  locations  ~>e  waranty  is 
void  if  the  Equipment  or  Software  has  been  subjected  to  improper  or  abnormal  use  If  a  manufacturing  defect  is 
discovered  dunng  the  stated  warranty  period  the  detective  Equipment  must  be  returned  to  a  Radio  Shack 
Computer  Center,  a  Radio  Shack  retail  store,  a  participating  Radio  Shack  Iranchisee  or  a  participating  Radio  Shack 
dealer  tor  repair,  along  with  a  copy  of  the  sales  document  or  lease  agreement  The  original  CUSTOMER'S  sole  and 
exclusive  remedy  in  the  event  of  a  defect  is  limited  to  the  correction  of  the  detect  by  repair,  replacement,  or 
refund  ol  the  purchase  price,  at  RADIO  SHACK'S  election  and  sole  expense.  RADIO  SHACK  has  no  obligation  to 
replace  or  'epa  ■  expendable  items 

B.  RADiO  SHACK  manes  no  warranty  as  to  the  design,  capability,  capacity,  or  suitability  for  use  of  the  Software. 
except  as  provided  in  this  paragraph.  Software  is  licensed  on  an  "AS  IS"  basis,  without  warranty.  The  original 
CUSTOMER'S  exclusive  remedy,  in  the  event  ot  a  Software  manufactunng  defect  is  its  'epair  or  replacement 
within  thirty  (30)  calendar  days  of  the  date  of  the  Radio  Shac<  sales  document  received  upon  license  of  the 
Software.  The  defective  Software  shall  be  returned  to  a  Radio  Shack  Computer  Center,  a  Radio  Shack  retail  store, 
a  participating  Radio  Shacx  franchisee  or  Radio  Shack  dealer  along  with  the  sales  document 

C.  Except  as  provided  herein  no  employee,  agent,  franchisee,  dealer  or  other  person  is  authorized  to  give  any 
warranties  o!  any  nature  on  ber-alt  c'  RAD  0  SHACK. 

0  EXCEPT  AS  PROVIDED  HEREIN,  RADIO  SHACK  MAKES  NO  EXPRESS  WARRANTIES,  AND  ANY  IMPLIED 
WARRANTY  OF  MERCHANTABILITY  OR  FITNESS  FOR  A  PARTICULAR  PURPOSE  IS  LIMITED  IN  ITS  DURATION 
TO  THE  DURATION  OF  THE  WRITTEN  LIMITED  WARRANTIES  SET  FORTH  HEREIN. 

F  Sorre  states  do  not  allow  limitations  on  how  long  an  implied  warranty  lasts,  so  the  above  limdation(s)  may  not 
appiy  to  CUSTOMER. 

LIMITATION  OF  LIABILITY 

A  EXCEPT  AS  PROVIDED  HEREIN,  RADIO  SHACK  SHALL  HAVE  NO  LIABILITY  OR  RESPONSIBILITY  TO  CUSTOMER 
OR  ANY  OTHER  PERSON  OR  ENTITY  WITH  RESPECT  TO  ANY  LIABILITY,  LOSS  OR  DAMAGE  CAUSED  OR 
ALLEGED  TO  BE  CAUSED  DIRECTLY  OR  INDIRECTLY  BY  "EQUIPMENT"  OR  "SOFTWARE"  SOLD,  LEASED, 
LICENSED  OR  FURNISHED  BY  RADIO  SHACK,  INCLUDING,  BUT  NOT  LIMITED  TO,  ANY  INTERRUPTION  OF 
SERVICE,  LOSS  OF  BUSINESS  OR  ANTICIPATORY  PROFITS  OR  CONSEQUENTIAL  DAMAGES  RESULTING  FROM 
THE  USE  OR  OPERATION  OF  THE  "EQUIPMENT"  OR  "SOFTWARE."  IN  NO  EVENT  SHALL  RADIO  SHACK  BE 
LIABLE  FOR  LOSS  OF  PROFITS,  OR  ANY  INDIRECT,  SPECIAL,  OR  CONSEQUENTIAL  DAMAGES  ARISING  OUT  OF 
ANY  BREACH  OF  THIS  WARRANTY  OR  IN  ANY  MANNER  ARISING  OUT  OF  OR  CONNECTED  WITH  THE  SALE, 
LEASE,  LICENSE,  USE  OR  ANTICIPATED  USE  OF  THE  "EQUIPMENT"  OR  "SOFTWARE." 

NOTWITHSTANDING  THE  ABOVE  LIMITATIONS  AND  WARRANTIES.  RADIO  SHACKS  LIABILITY  HEREUNDER  FDR 
DAMAGES  INCURRED  BY  CUSTOMER  OR  OTHERS  SHALL  NOT  EXCEED  THE  AMOUNT  PAID  BY  CUSTOMER  FOR 
THE  PARTICULAR  "EQUIPMENT"  OR  "SOFTWARE"  INVOLVED. 

B  RADIO  SHACK  shall  not  be  liable  for  any  damages  caused  by  delay  in  delivenng  or  furnishing  Equipment  and/or 
Software. 

C.  No  action  arising  out  ol  any  claimed  breach  ot  this  Warranty  or  transactions  under  this  Warranty  may  be  brought 
more  than  two  (2)  years  after  the  cause  of  action  has  accrued  or  more  than  tour  (4)  years  after  the  date  of  the 
Radio  Shack  sales  document  tor  the  Equipment  or  Software,  whichever  first  occurs 

0.  Some  states  do  not  allow  the  limitation  or  exBlasfon  ot  icidentai  or  consequential  damages,  so  the  above 
limitation's)  or  exclusion(s)  may  not  apply  to  CUSTOMER. 

SOFTWARE  LICENSE 

RADIO  SHACK  grants  to  CUSTOMER  a  non-exclusive,  paid-up  license  to  use  the  TANDY  Software  on  one  computer, 

subject  to  the  following  provisions: 

A     Except  as  otherwise  provided  in  this  Software  License,  applicable  copyright  laws  shall  apply  to  the  Software. 

B.  Title  to  the  medium  on  which  the  Software  is  recorded  (cassette  and/or  diskette)  or  stored  (ROM)  is  transferred  to 
CUSTOMER,  but  not  title  to  the  Software. 

C.  CUSTOMER  may  use  Software  on  a  multiuser  or  network  system  only  it  either,  the  Software  is  expressly  labeled 
to  be  for  use  on  a  multiuser  or  network  system,  or  one  copy  ot  this  software  is  purchased  for  each  node  or 
terminal  on  which  Software  is  to  be  used  simultaneously. 

0.  CUSTOMER  shall  not  use.  make,  manufacture,  or  reproduce  copies  of  Software  except  tor  use  on  one  computer 
and  as  is  specifically  provided  in  this  Software  License.  Customer  is  expressly  prohibited  from  disassembling  the 
Software. 

E.  CUSTOMER  is  permitted  to  make  additional  copies  ol  the  Software  only  tor  backup  or  archival  purposes  or  it 
additional  copies  are  required  in  the  operation  ol  one  computer  with  the  Software,  but  only  to  the  extent  the 
Software  anows  a  backup  copy  to  be  made.  However,  tor  TRSDOS  Software.  CUSTOMER  is  permitted  to  make  a 
limited  numoer  ot  additional  copies  lor  CUSTOMER'S  own  use. 

F.  CUSTOMER  may  resell  or  distnbute  unmodilied  copies  ol  the  Software  provided  CUSTOMER  has  purchased  one 
copy  ot  the  Software  for  each  one  sold  or  distributed.  The  provisions  ot  this  Software  License  shall  also  be 
applicable  to  third  parties  receiving  copies  ol  the  Software  Irom  CUSTOMER 

G     All  copyright  notices  shall  be  retained  on  all  copies  of  the  Software. 

APPLICABILITY  OF  WARRANTY 

A.  The  terms  and  conditions  ol  this  Warranty  are  applicable  as  between  RADIO  SHACK  and  CUSTOMER  lo  either  a 
sale  of  the  Equipment  and/or  Software  License  to  CUSlOMER  cr  to  a  transaction  whereby  Radio  Shack  sells  or 
conveys  such  Equipment  to  a  third  party  lor  lease  to  CUSTOMER. 

B.  The  limitations  of  liability  and  Warranty  provisions  herein  shall  inure  to  the  benefit  ot  RADIO  SHACK,  the  author, 
owner  and  or  'icensor  of  the  Software  and  any  manufacturer  of  the  Equipment  sold  by  Radio  Shack 

STATE  LAW  RIGHTS 

The  warranties  granted  herein  give  the  original  CLS'OMER  specific  legal  rights,  and  the  original  CUSTOMER  may 

have  other  rights  which  vary  Irom  state  lo  state.  4,87 
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OS-9  Level  Two  Operating  System  (software): 

©  1986,  Microware  Systems  Corporation 

Licensed  to  Tandy  Corporation. 

All  Rights  Reserved. 

All  portions  of  this  software  are  copyrighted  and  are  the 
proprietary  and  trade  secret  information  of  Tandy 
Corporation  and/or  its  licensor.  Use,  reproduction  or 
publication  of  any  portion  of  this  material  without  the 
prior  written  authorization  by  Tandy  Corporation  is 
strictly  prohibited. 

OS-9  Level  T\vo  Operating  System  (manual): 

©  1986,  Tandy  Corporation. 

All  Rights  Reserved. 

Reproduction  or  use  of  any  portion  of  this  manual,  without 
express  written  permission  from  Tandy  Corporation  and/or 
its  licensor,  is  prohibited.  While  reasonable  efforts  have 
been  made  in  the  preparation  of  this  manual  to  assure  its 
accuracy,  Tandy  Corporation  assumes  no  liability 
resulting  from  any  errors  in  or  omissions  from  this 
manual,  or  from  the  use  of  the  information  contained 
herein. 

Tandy  is  a  registered  trademark  of  Tandy  Corporation. 

OS-9  is  a  trademark  of  Microware  Systems  Corporation. 

BASIC09  is  a  trademark  of  Microware  Systems 
Corporation  and  Motorola,  Inc. 
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About  This  Manual 


Using  Your  OS-9  Handbook 

If  you  feel  that  starting  a  new  computer  operating  system  is  a 
"scary  business,"  relax.  This  handbook  is  designed  to  put  you  at 
ease  when  using  OS-9.  It  is  divided  into  two  parts— each  part  has 
a  different  purpose. 

What  is  in  Part  1 

"Part  1"  of  this  handbook  is  designed  to  show  you,  step  by  step, 
how  to  set  up  and  use  your  computer  with  OS-9.  Follow  the  steps 
as  they  are  described,  and  OS-9  is  your  obedient  servant.  The  few 
instructions  in  "Part  1"  are  all  that  many  OS-9  users  ever  need. 

What  is  in  Part  2 

"Part  2"  is  for  the  more  adventurous.  OS-9  has  an  extensive  rep- 
ertoire of  commands  and  functions  to  create  and  manage  data  and 
to  make  use  of  peripherals  (devices  you  can  connect  to  your  com- 
puter, such  as  disk  drives  and  printers).  If  you  want  to  learn  more 
about  the  operating  system,  and  if  you  like  to  explore,  "Part  2"  is 
for  you.  You  leam  other  useful  OS-9  commands  that  prepare  you 
to  make  use  of  all  the  functions  and  commands  described  in 
OS-9  Commands. 
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What  You  Need  to  Know 
To  Use  Floppy  Drives 


Floppy  diskettes  require  careful  handling.  You  might  already  be 
familiar  with  how  to  take  care  of  diskettes  from  reading  your 
Color  Computer  Disk  System  manual.  If  not,  or  as  a  reminder, 
review  the  following  points: 

•  Always  make  copies  of  important  diskettes.  The  price  of  a 
diskette  is  small  compared  to  the  time  it  can  take  to 
replace  destroyed  data. 

•  Copy  data  you  are  working  with  regularly.  If  you  experi- 
ence a  power  failure  while  using  your  computer,  the  data 
on  any  diskettes  you  have  in  a  drive  can  be  destroyed. 
Other  accidents  can  happen  as  well. 

•  Always  keep  the  protective  paper  or  cardboard  envelope  on 
your  diskette  when  it  is  not  in  use. 

•  Your  drive  accesses  a  diskette  through  the  oblong  slot  in 
the  diskette's  jacket.  Never  touch  the  diskette  through 
this  hole.  The  oil  from  even  the  cleanest  hand  can  destroy 
data,  making  the  diskette  useless. 

•  Do  not  bend  diskettes. 

•  Store  diskettes  away  from  excessive  heat,  dust,  and  any 
magnetic  source.  Even  components  in  disk  drives,  video 
displays,  TVs,  and  electric  motors  can  garble  the  data  on 
diskettes. 

•  If  you  must  write  on  a  diskette  label  after  placing  it  on 
the  diskette,  use  only  a  soft  felt  pen. 

•  Do  not  switch  your  computer,  disk  drive(s),  or  Multi-Pak 
interface  on  or  off  while  you  have  a  diskette  in  a  disk 
drive. 
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Write  Protection  for  Diskettes 


Write-Protect  Notch 
'^2- Tab 


Most  diskettes  have  a  square  notch  cut  from  one  corner.  This  is  a 
write  protect  notch.  If  you  place  a  special  adhesive  tab  (supplied 
with  diskettes)  over  both  sides  of  this  notch,  your  computer  can  no 
longer  write  (store)  data  on  it.  This  feature  protects  diskettes  from 
inadvertent  destruction  of  data. 

Removing  the  tab  again  lets  you  write  data  onto  the  diskette. 

Disk  Drive  Names 

OS-9  has  its  own  method  of  referring  to  your  disk  drives.  What 
your  Color  Computer  Disk  System  manual  calls  Drive  0,  OS-9  calls 
Drive  /DO.  This  is  your  first  drive  if  you  have  more  than  one 
floppy  disk  drive  connected  to  your  system.  Subsequent  drives  are 
named  /Dl,  /D2,  and  so  on. 

If  you  have  a  hard  disk  attached  to  your  system,  OS-9  refers  to  it 
as  Drive  /HO.  A  second  hard  disk  drive  is  named  /HI. 
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Making  Copies  of  Diskettes 

Before  you  can  store  iriformation  on  a  diskette,  you  must  format  it. 
Formatting  is  the  process  of  magnetically  arranging  a  disk's  sur- 
face so  that  OS-9  can  store  and  locate  information.  The  following 
steps  tell  you  how  to  format  a  diskette.  Format  at  least  two 
diskettes  at  this  time  to  use  in  making  backups  (copies)  of  your 
two  OS-9  system  diskettes.  If  you  have  other  important  diskettes 
to  backup,  format  as  many  diskettes  as  you  require. 


Formatting  With  One  Disk  Drive 

1.  If  you  have  not  already  done  so,  place  a  write-protect  tab  on 
your  System  Master  diskette.  Then,  turn  on  and  boot  your 
computer  as  described  in  Chapter  2. 

2.  With  the  OS-9  System  Master  diskette  in  your  drive,  type: 


load    format  [ENTER]. 

3.  Select  a  diskette  that  does  not  contain  data  or  that  contains 
data  you  do  not  want  to  keep.  Make  sure  it  does  not  have  a  foil 
tab  covering  the  write-protect  notch.  Put  it  in  your  disk  drive 
(Drive  /Dffl  in  place  of  your  OS-9  System  Master  diskette  and 
type: 


format    /d0     ENTER 


The  following  prompt  appears: 

COLOR   COMPUTER   FORMATTER 
Formatting    drive    /DB 
y    (yea)    or    n    (no) 
Ready? 

4.  Press  (T|  to  begin  formatting.  OS-9  asks  you  for  a  Disk  Name:. 
Type  any  name,  using  a  maximum  of  32  characters.  For 
example,  you  can  type  s  |  ENTER  |  to  name  the  diskette  "s." 

Next  OS-9  verifies  that  the  diskette  is  formatted  properly.  The 
screen  shows  each  track  number  in  hexadecimal  notation  dur- 
ing verification.  A  track  is  a  concentric  ring  around  the 

diskette  on  which  information  is  stored, 
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5.  When  formatting  is  complete,  OS-9  shows  you  the  Number  of 
good  sectors.  This  number  depends  on  the  type  of  disk  drive 
you  are  using.  For  a  35  track,  single-sided  drive,  the  number 
should  be  $000276  (hexadecimal  276  sectors).  The  OS-9  prompt 
and  cursor  reappear.  Remove  the  newly  formatted  diskette  from 
the  drive,  and  store  it  in  a  safe  place  until  you  are  ready  to  use 
it. 

Format  as  many  diskettes  as  you  need  by  following  Steps  3 
through  5. 

Formatting  With  Two  Disk  Drives 

1.  If  your  computer  is  off,  turn  it  on,  and  boot  OS-9  as  outlined  in 
Chapter  2. 

2.  At  the  system  prompt  (OSS;),  type  format  /dl  [ enter |.  The 
screen  shows: 

COLOR  COMPUTER  FORMATTER 
Formatting  drive  /d1 
y  (yes)  or  n  (no) 
Ready? 

3.  Insert  a  blank  disk,  or  one  which  does  not  contAin  data  you 
want  to  keep,  into  Drive  /Dl,  and  close  the  latch.  Be  sure  the 
diskette  does  not  have  a  foil  tab  covering  the  write-protect 
notch.  Press  (T). 

4.  OS-9  formats  the  diskette;  then  asks  you  for  a  Disk  Name:. 
Type  any  name,  using  a  maximum  of  32  characters.  For 
example,  you  can  type  s  |  enter  [  to  name  the  diskette  "s." 

Next  OS-9  verifies  that  the  diskette  is  formatted  properly,  The 

screen  shows  each  track  number  in  hexadecimal  notation  dur- 
ing verification.  A  track  is  a  concentric  ring  around  the 
diskette  on  which  information  is  stored. 

5.  When  formatting  finishes,  OS-9  shows  you  the  Number  of 
good  sectors.  This  number  depends  on  the  type  of  disk  drive 
you  are  using.  For  a  35-track,  single-sided  drive,  the  number 
should  be  $000276  (hexadecimal  276  sectors).  The  OS-9  prompt 
and  cursor  reappear.  Remove  the  newly  formatted  diskette  from 
the  drive,  and  store  it  in  a  safe  place  until  you  are  ready  to  use 
it. 
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Fbrmat  as  many  diskettes  as  you  need  by  following  the  same 
procedure. 

Using  the  Backup  Command 

BACKUP  is  one  OS-9  command  that  you  can  expect  to  use  fre- 
quently. It  is  the  command  you  use  to  make  copies  of  your 
diskettes.  We  strongly  recommend  that  you  now  use  the  fol- 
lowing instructions  to  make  copies  of  your  OS-9  system 

diskettes.  Ifru  can  only  copy  diskettes  that  are  created  in  the 
same  type  of  disk  drive  you  are  using.  "Ktur  OS-9  system  diskettes 
are  35  track,  single  sided. 

BACKUP  uses  two  terms  you  need  to  understand.  They  are  source 
and  destination.  A  source  diskette  is  the  diskette  that  contains  the 
program,  file  or  data  that  you  want  to  backup.  The  destination 
diskette  is  the  blank  formatted  diskette  you  prepared  to  receive 
the  copied  data. 

Note:  Some  application  programs  you  buy  do  not  let  you 
make  copies  of  their  diskettes.  Check  the  program  manual 
for  information  on  protecting  the  data  on  these  diskettes. 


Making  Copies  With  One  Disk  Drive 

1.  If  your  computer  is  off,  turn  it  on,  a 
the  beginning  of  Chapter  2. 

2.  At  the  system  prompt  (0S9:),  type: 


1.  If  your  computer  is  off,  turn  it  on,  and  boot  OS-9  as  outlined  at 
the  beginning  of  Chapter  2. 


backup    /d0    *32K  |  ENTER] 

This  tells  OS-9  to  make  a  backup  of  the  diskette  in  Drive  /DO. 

The  screen  displays  the  following  prompt: 

Ready    to    backup    from    /d0    to    /d0 

7  j 

3.  Leave  the  System  Master  diskette  in  Drive  /DO  to  make  a 
backup  of  it.  To  back  up  one  of  your  other  diskettes,  for  exam- 
ple the  BASIC09/CONFIG  diskette,  remove  the  System  Master 
diskette  and  replace  it  with  the  diskette  you  want  to  copy. 

4.  Press  (T)  when  you  are  ready  to  continue.  The  screen  displays: 

Ready   destination,    hit    a    key 
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5.  Replace  the  source  diskette  with  the  destination  diskette.  Then, 
press  the  space  bar  to  continue  BACKUP. 

When  you  back  up  one  diskette  to  another,  any  data  previ- 
ously existing  on  the  destination  diskette  is  overwritten 
(destroyed).  OS-9  gives  you  a  chance  to  make  sure  you  have 
inserted  the  proper  destination  diskette  by  displaying  the 
message; 

DISK  NAME 

is    being    scratched 
Ok    ?: 

"Scratched"  means  that  OS-9  is  going  to  replace  any  data  on 
the  diskette  with  new  data  from  the  source  diskette.  BACKUP 
also  gives  the  destination  diskette  the  same  name  as  the  source 
diskette — the  destination  becomes  a  duplicate  of  the  source. 

6.  Press  (T)  to  keep  going.  The  screen  asks  you  to: 

Ready   Source,    hit    a    key: 

7.  Remove  the  formatted  diskette  from  Drive  /DO,  and  replace  it 
with  the  source  diskette  that  contains  the  data  you  want  to 
copy.  Press  the  space  bar. 

In  a  moment,  a  prompt  asks  you  to: 

Ready   Destination,    hit    a    key: 

8.  Remove  the  source  diskette  and  replace  it  with  the  destination 
diskette.  Press  the  space  bar. 

9.  Continue  switching  diskettes  as  the  screen  instructs  you  until 
you  see: 

Sectors    copied:  $0278 
Verify  pass 

Followed  in  a  moment  by: 

Sectors  verified:  $0276 

DS9: 


3-6 


What  You  Need  to  Know  To  Use  Floppy  Drives  1 3 


The  diskette  now  in  your  drive,  the  destination  diskette,  is  a 
duplicate  of  the  source  diskette.  If  you  copied  the  System  Master 
or  the  BASIC09/CONFIG  diskette,  store  it  in  a  safe  place,  and  use 
the  copy  as  your  working  diskette.  Reserve  the  original  diskette 
for  making  future  backups. 

Note:  For  computers  with  512K  of  memory,  OS-9  can  backup 
a  diskette  fester  if  your  replace  #32K  in  Step  2  with  #56K. 


Making  Copies  With  Two  Disk  Drives 

1.  If  your  computer  is  off,  turn  it  on,  and  boot  OS-9  as  outlined  at 

the  beginning  of  Chapter  2. 

2.  At  the  system  prompt  (DS9:),  type: 


backup    /d0    /d1    *32K  fENTERl 
This  tells  OS-9  to  make  a  backup  of  the  diskette  in  Drive  /DO. 
The  screen  displays  the  following  prompt: 

Ready    to   backup   from    /d0    to    /d1 

3.  Leave  the  System  Master  diskette  in  Drive  /DO  to  make  a 

backup  of  it.  To  back  up  one  of  your  other  diskettes,  for  exam- 
ple the  BASIC09/CONFIG  diskette,  remove  the  System  Master 
diskette  and  replace  it  with  the  diskette  you  want  to  copy. 

4.  Press  (T|  when  you  are  ready  to  continue. 

When  you  back  up  one  diskette  to  another,  the  process  over- 
writes or  destroys  any  data  previously  existing  on  the  destina- 
tion diskette.  OS-9  gives  you  a  chance  to  make  sure  you  have 
inserted  the  proper  destination  diskette  by  displaying  the 
message: 

DISK  NAME 

is    being    scratched 
Ok    ?: 

"Scratched"  means  that  OS-9  replaces  any  data  on  the  des- 
tination diskette  with  new  data  from  the  source  diskette.  As 
well,  BACKUP  gives  the  destination  diskette  the  same  name 
as  the  source  diskette — the  destination  becomes  an  exact 
duplicate  of  the  source. 
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6.  Press  [TJ  to  keep  going. 

Copying  continues.  When  the  procedure  ends,  you  see: 

Sectors    copied:  $0276 
Verify  pas5 

Followed  in  a  moment  by: 

Sectors  verified:  $0276 
OS9: 

The  diskette  in  Drive  /Dl  is  now  a  duplicate  of  the  source 
diskette.  If  you  copied  the  System  Master  or  the  BASIC09/ 
CONFIG  diskette,  store  it  in  a  safe  place,  and  use  the  copy  as 
your  working  diskette.  Reserve  the  original  diskette  for  making 
future  backups. 

Note:  For  computers  with  512K  of  memory,  OS-9  can  backup 
a  diskette  faster  if  you  replace  #32K  in  Step  2  with  #56K. 
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How  to  Start  and  Exit  'Your 
System 


Starting  your  computer  and  initializing  an  operating  system  is 
called  booting.  In  a  sense,  the  computer  is  pulling  itself  up  by  its 
bootstraps. 

To  run  OS-9,  Level  II,  you  must  have  a  Color  Computer  3  with  at 
least  one  floppy  disk  drive.  "¥bur  OS-9  system  diskette  includes 
modules  to  support  the  following  Color  Computer  hardware: 

•  Up  to  512K  RAM 

•  A  Keyboard 

•  An  Alphanumeric  Video  Display 

•  A  Color  Graphics  Display 

•  Floppy  Disk  Drives  (one  or  two) 

•  Joysticks  (one  or  two) 

•  A  Serial  Printer 

•  An  RS-232C  Communications  Port 

If  you  connect  a  Multi-Pak  Interface  to  your  computer,  and  use 
the  CONFIG  utility  from  your  BASIC09/CONFIG  diskette  (see 
Chapter  7),  OS-9  can  support  the  following  devices: 

•  As  many  as  two  external  RS-232  communications  cards 

•  As  many  as  two  modem  paks 

•  As  many  as  two  additional  floppy  disk  drives 

Note:  The  Multi-Pak  Interface  has  four  cartridge  slots. 
A  floppy  disk  controller  must  be  in  Slot  4.  %u  can  put 
modem  paks,  or  RS-232  paks  in  Slots  1,  2,  or  3. 
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Booting  OS-9 

Use  the  instructions  in  the  Color  Computer  Disk  System  manual 
to  turn  on  your  computer  system.  After  you  do,  the  video  screen 
displays  a  copyright  message  followed  by  the  letters,  OK.  This  is 
Disk  Extended  Color  BASIC'S  way  of  telling  you  that  it  is  ready  to 
get  to  work.  It  is  waiting  for  your  commands. 

To  load  OS-9,  follow  these  steps: 

1.  Insert  the  OS-9  System  Master  diskette  into  Drive  0. 

2.  At  the  OK  prompt,  type: 


DOS  I  ENTER  I 


OS-9  starts.  If  the  DOS  command  returns  a  syntax  error  (SN? 
error),  be  sure  you  entered  the  command  correctly.  If  DOS 
still  returns  the  error,  check  to  make  sure  you  have  installed 
your  disk  cartridge  properly. 

3.  After  OS-9  displays  its  startup  message,  this  prompt  appears: 

yy/mm/dd    hh:mm:ss 
TIME? 

4.  Type  the  year,  month,  date,  hours,  minutes,  and  seconds  in  the 
format  requested;  then  press  I  enter  |.  For  instance,  if  the  date 
and  time  is  September  3,  1986,  1:22  p.m.,  type: 


86/09/03    13;22  I  ENTER  I 


Note  that  the  time  is  entered  in  24-hour  notation  and  that  the 
seconds  (:SS)  are  optional, 

You  can  bypass  this  time  and  date  prompt  by  only  pressing 
I  enter  |.  However,  if  you  do,  OS-9  cannot  provide  the  correct  date 
when  you  create  and  save  data  on  disk.  Also,  it  cannot  provide 
the  correct  date  and  time  for  application  programs  that  require 
them. 

After  you  enter  the  date  and  time,  the  OS-9  prompt  appears 
and  OS-9  is  now  in  control  and  ready  to  accept  a  command. 

You  should  always  keep  the  OS-9  System  diskette  in  Drive  0 
(/DO)  while  running  OS-9  unless  you  have  a  hard  disk  con- 
taining your  system  files.  An  OS-9  System  diskette  is  a  backup 
copy  of  the  OS-9  System  Master  diskette.  The  instructions  for 
making  copies  are  in  the  next  chapter. 
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Rebooting  OS-9 

If  you  need  to  reboot  OS-9  after  the  initial  startup,  press  your 
computer's  reset  button  (located  at  the  right  rear  of  the  com- 
puter). Pressing  the  reset  button  one  time  causes  the  OS-9  boot 
message  to  reappear.  The  system  then  loads  as  it  did  originally. 
Be  sure  the  System  Master  diskette  is  in  Drive  /DO  when  you 
reboot. 

Pressing  the  reset  button  twice  returns  the  computer  to  Disk 
BASIC. 


Exiting  OS-9 

In  the  same  manner  that  you  use  OS-9  to  start  operations,  you 

should  use  OS-9  to  exit  or  close  operations.  For  instance,  if  you  are 
in  the  middle  of  a  process,  it  is  unwise  to  suddenly  turn  off  your 
computer.  Doing  so  can  destroy  files  or  garble  disks. 

You  can  usually  terminate  an  operation  by  pressing  |  break  |  or 
I  ctrl  |  (JJ.  In  some  instances,  you  must  let  an  operation  complete 
its  function  before  you  can  regain  control  of  OS-9.  If  you  are  using 
an  application  program,  that  program's  manual  tells  you  how  to 
exit  the  program  to  the  OS-9  command  level. 

You  should  always  be  at  the  OS-9  command  level  to  turn  off  your 
computer.  Then  follow  these  steps: 

1.  Be  sure  the  OS-9  system  prompt  and  cursor  are  displayed. 

Note:  You  can  turn  off  the  OS-9  cursor.  If  you  or  an 
application  program  has  done  so,  the  cursor  does  not  dis- 
play at  the  command  level. 

2.  Take  out  any  floppy  diskettes  from  the  disk  drives,  put  them 
back  in  their  protective  envelopes,  and  store  them  in  a  safe 
place. 

3.  Turn  off  all  the  equipment  attached  to  your  computer  such  as 
a  printer  or  disk  drive(s);  then  turn  off  your  TV  or  monitor. 
Last  of  all,  turn  off  your  computer  and  Multi-Pak  Interface  (if 
you  have  one).  If  you  plug  your  equipment  into  a  power  strip, 
you  can  use  the  power  strip  switch  to  turn  off  all  equipment  at 
one  time. 
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Upper-  and  Lowercase  Characters 

OS-9  can  display  both  upper-  and  lowercase  letters.  However,  you 
can  tell  it  you  want  to  use  only  uppercase.  To  do  this,  type: 


tmode   upc  [  ENTER  | 

If  you  do  this,  you  cannot  type  lowercase  letters,  and  the  system 
displays  all  uppercase  letters.  To  switch  back  to  both  uppercase 
and  lowercase,  type: 


tmode   -upc  1  enter  1 

Even  when  you  are  in  the  upper-/lowercase  mode,  you  can  switch 
to  typing  all  uppercase  by  pressing  |  ctrl  |  {q}.  Everything  you  type 
is  now  uppercase,  but  the  computer  can  display  both  upper-  and 
lowercase.  Press  |  ctrl  |  QT)  to  switch  back  to  upper-/lowercase. 

If  you  want  to  type  only  one  uppercase  letter,  hold  down  1  shift  | 
while  you  press  that  letter. 

It  does  not  matter  to  OS-9  whether  you  type  in  uppercase  or  low- 
ercase letters,  or  any  combination  of  upper-  and  lowercase  let- 
ters. For  instance,  instead  of  typing  TMODE  UPC,  you  can  type 
tmode   upc  or  Tmode    UPC. 

OS-9  Error  Messages 

Everyone  makes  a  mistake  now  and  then  when  typing  com- 
mands. If  you  type  something  the  operating  system  doesn't  rec- 
ognize, or  if  you  ask  it  to  do  something  it  cannot  do,  it  displays  an 
error  message.  This  message  is  a  number  that  refers  to  the  type 
of  problem  that  OS-9  has  encountered.  For  instance,  if  you  type 
xx xx  |  enter  I  (which  is  nonsense  to  OS-9),  the  system  displays: 

Error    #216 

If  you  don't  know  the  meaning  of  the  system  error  number  you 
have  two  options:  (1)  you  can  look  up  the  reference  in  OS-9 
Commands  under  Appendix  A,  "Error  Codes"  or,  (2)  you  can  type: 


Error    216  I  ENTER  I 


Either  method  shows  you  that  Error  #216  means  "Path  Name  Not 
Found."  OS-9  thought  you  wanted  it  to  execute  a  command  but  it 
could  not  find  one  named  xxxx. 
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Other  OS-9  error  messages  tell  you  if  you  have  used  all  of  a  disk's 
storage  space,  if  the  computer's  memory  is  full,  if  you  try  to  cre- 
ate two  files  with  the  same  name,  and  so  on. 
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What  is  an  Operating  System? 


OS-9  is  a  disk  Operating  System  (that's  what  OS  stands  for).  An 
operating  system  is  a  group  of  programs  acting  as  a  message 
center  and  an  interpreter.  Using  your  instructions,  an  operating 
system  manages  the  computer's  working  circuits. 

In  fact,  thinking  of  OS-9  as  your  computer  manager  is  helpful. 
The  boss  (that's  you)  gives  orders.  OS-9  (the  manager)  sees  they 
get  done. 

To  operate  OS-9  you  need  at  least  one  floppy  disk  drive  attached 
to  your  computer.  OS-9  is  originally  configured  to  recognize  two 
floppy  disk  drives.  Later,  this  handbook  describes  how  to  let  OS-9 
know  if  you  have  more  than  two  floppy  disk  drives,  or  if  you  have 
other  hardware  (printers,  modems,  hard  disks,  and  so  on)  you 
want  it  to  recognize. 

Instructing  Your  Operating  System 

You  give  your  commands  to  OS-9  by  typing  them.  Because  OS-9 
does  exactly  (and  only)  what  you  tell  it,  your  entries  must  be  pre- 
cise and  have  perfect  syntax  (spelling  and  form).  You  must  also  be 
sure  to  give  OS-9  every  detail  it  needs  to  perform  a  task. 

For  instance,  if  you  told  your  office  manager  to,  "Make  a  phone 
call,"  what  can  the  manager  do?  Obviously,  not  much  that  is 
helpful  to  you.  The  manager  must  know  who  to  call,  the  phone 
number,  and  what  to  say.  OS-9  is  the  same.  It  must  have  all  the 
details  before  it  can  carry  out  your  commands  properly. 

To  show  you  how  to  instruct  your  operating  system,  the  hand- 
book asks  you  to  type  characters,  words,  and  lines  on  your  key- 
board. When  you  do,  you  are  issuing  commands  to  OS-9. 
Technically,  a  command  is  only  one  word  that  describes  the  action 
you  want  OS-9  to  perform.  A  command  line  is  a  command  with  all 
of  its  qualifiers. 

In  this  manual,  command  lines  usually  contain  words  in  boxes, 
such  as  |  enter  |.  These  indicate  keys  that  you  press. 

The  manual  also  asks  you  to  press  key  sequences.  For  instance, 
when  asked  to  press  |~ctrT|  [cj,  hold  down  the  key  marked  CTRL, 
and  while  holding  down  |  ctrl  1,  press  [cj. 
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Characters  that  are  not  in  boxes  are  typed  individually.  For 
instance,  if  you  are  asked  to  type  the  command  line  format  /d0 
[TntIrI,  press  each  key  individually  (CDQDECIJSCDOCDGD 
r^fWJEFTl). 

If  you  make  a  mistake  while  typing,  use  [+3  to  move  back  to  the 
error.  Then  retype  that  portion  of  the  line. 

Using  Application  Programs  and 
Computer  Languages 

A  computer  application  is  a  program  designed  to  accomplish  spe- 
cific tasks.  There  are  application  programs  to  help  you  write  let- 
ters or  documents  (word  processors),  keep  a  mailing  list  (data 
managers),  and  keep  financial  records  (accounting  packages). 
There  are  also  programs  to  help  you  study  for  a  test,  play  a  game, 
play  music,  draw  a  picture,  and  much  more. 

Such  application  programs  usually  require  that  you  use  OS-9  to 
start  your  computer.  A  few  application  programs  let  you  start 
directly  from  the  application  diskette.  Different  programs  can 
require  different  procedures,  and  you  should  check  your  applica- 
tion program's  documentation  for  specific  instructions. 

Application  programs  have  special  screen  displays  and  menus  to 
instruct  you,  or  that  require  you  to  perform  a  particular  action, 
such  as  press  a  key.  When  you  are  operating  from  an  application 
program,  that  program  passes  your  instructions  to  OS-9.  OS-9 
manages  the  computer's  operations  in  the  background,  and  its 
functions  are  invisible  to  you. 

You  can  also  use  computer  languages  to  write  your  own  applica- 
tion programs.  BASIC  is  a  language.  If  you  read  the  Color 
Computer  Disk  System  manual,  you  already  know  a  bit  about  it. 
There  are  languages  you  can  purchase  to  use  with  OS-9  to  cre- 
ate programs,  such  as  assembly  language,  Pascal,  C,  and 
BASIC-09. 

Like  application  programs,  each  language  has  its  own  startup 
method.  The  manuals  that  come  with  the  languages  tell  you  how 
to  get  them  running  on  your  Color  Computer  3. 
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Using  Peripherals 

OS-9  lets  you  control  much,  more  than  your  computer's  opera- 
tions. It  also  gives  you  control  over  other  hardware  devices  such  as 
disk  drives,  a  printer,  modems,  windows,  other  terminals,  and  so 
on. 

Each  device  has  a  "System  Name,"  an  abbreviation  preceded  by  a 
slash  (/).  OS-9  can  only  recognize  a  device  if  you  type  its  name 
exactly  as  shown  below.  See  Chapter  7,  "Customizing  Your 
System"  for  information  on  how  to  tell  OS-9  what  devices  you 
want  it  to  handle. 

System 

Name Description 

/P  A  printer  connected  through  your  computer's  RS- 

232  port.  The  RS-232  port  is  a  serial  port,  and 
you  must  have  a  printer  with  a  serial  connection, 
such  as  the  Radio  Shack®  DMP  430. 

/Tl  A  data  terminal  or  another  computer  acting  as  a 

terminal,  connected  through  the  RS-232  port  of 
your  computer.  If  you  are  using  another  computer 
as  a  terminal,  it  must  run  a  terminal  program 
that  makes  it  perform  as  a  terminal. 

/T2  Another  data  terminal  or  another  computer  act- 

ing as  a  terminal,  connected  to  an  optional  RS- 
232  communications  pak  in  a  Multi-Pak  Inter- 
face. If  you  are  using  another  computer  as  a  ter- 
minal, it  must  run  a  terminal  program  that 
makes  it  perform  as  a  terminal. 

/T3  Another  data  terminal  or  another  computer  act- 

ing as  a  terminal,  connected  to  the  optional  RS- 
232  communications  pak  in  a  Multi-Pak 
Interface.  If  you  are  using  another  computer  as  a 
terminal,  it  must  run  a  terminal  program  that 
makes  it  perform  as  a  terminal. 

/Ml  A  modem  using  an  optional  300-baud  modem  pak 

in  the  optional  Multi-Pak  Interface.  A  modem 
allows  you  to  communicate  with  other  computers 
either  directly  or  over  phone  lines. 
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System 

Name  Description 


/M2  Another  modem  using  an  optional  300-baud 

modem  pak  in  the  optional  Multi-Pak  Interface. 

/DO  A  floppy  disk  drive. 

/Dl  Another  floppy  disk  drive 

AV,  AVI,  Windows  that  you  can  establish  on  your  OS-9 

/W2,  AV3  system.  Yaa  use  I  cleah  [  to  page  among  windows 

AV4,  AV5  you  create.  See  "Using  Windows"  in  Chapter  7 

AV6,  AV7  and  OS-9  Windowing  System  Owner's  Manual  for 

information  on  creating  windows. 

Why  Use  OS-9? 

You  now  know  that  OS-9  is  an  operating  system  for  your  Color 
Computer.  You  might  also  have  heard  that,  in  the  world  of  com- 
puter operating  systems,  OS-9  is  a  leader.  Perhaps  that  is  why  you 
bought  it.  OS-9  stands  out  for  several  reasons.  Some  of  its  strong 
points  are: 

•  File  managing  capabilities. 

•  Multi-user  features.  With  OS-9,  more  than  one  person  can 
use  the  same  computer  at  the  same  time. 

•  Multi-tasking.  OS-9  can  handle  several  jobs  at  the  same 
time. 

•  Window  functions  that  let  you  divide  your  display  screens 
into  sections  in  which  you  can  have  one  or  more  opera- 
tions running,  all  at  the  same  time. 

•  Input/Output  capabilities.  OS-9  can  communicate  with 
TVs  and  monitors,  disk  drives,  printers,  and  other 
computers. 

•  A  sophisticated  repertoire  of  commands. 

•  Sophisticated  programming  languages. 

If  you  are  not  familiar  with  such  terms  as  files,  multi-user,  multi- 
tasking, and  commands,  don't  worry.  The  handbook  explains  these 
terms  and  more. 
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Programmers  like  OS-9  because  of  its  powerful  features.  It  lets 
them  show  off  all  of  their  skills.  As  a  result,  another  OS-9  fea- 
ture is  the  wide  range  of  excellent  programs  that  you  can  use 
with  the  system. 

How  Much  Do  You  Need  to  Know 
About  OS-9? 

Y)u  might  wonder  how  much  you  really  need  to  know  to  use  OS-9. 
The  answer  varies  with  your  needs,  and  with  the  application 
programs  you  intend  to  use. 

However,  regardless  of  how  you  intend  to  use  your  computer,  there 
are  some  OS-9  procedures  you  must  know.  For  instance,  you  must 
know  how  to  load  OS-9,  how  to  prepare  diskettes  to  store  data, 
and  how  to  make  copies  of  data  or  entire  diskettes.  This  part  of 
your  handbook  makes  these  jobs  easy. 

Regardless  of  how  careful  you  are,  there  are  times  when  things  go 
wrong.  When  this  happens,  OS-9  displays  an  error  message  on  the 
screen.  This  part  of  the  manual  also  helps  you  to  understand 
error  messages  and  what  to  do  about  them, 
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Before  you  can  use  OS-9  extensively,  you  need  to  know  how  the 
system  organizes  and  stores  data  on  disk.  The  information  in  this 
section  is  true  for  both  floppy  diskettes  and  hard  disks.  However, 
because  of  the  greater  storage  capacity  of  a  hard  disk,  it  is  of 
particular  importance  to  hard  disk  users. 

About  Files 

Consider  the  information  stored  on  disks  to  be  of  two  basic  types, 
programs  and  data.  A  program  is  code  that  causes  your  com- 
puter to  execute  a  task.  Data  is  information  that  a  program  uses 
or  that  a  program  creates. 

All  the  information  that  OS-9  stores  on  disks,  whether  program  or 
data,  is  stored  in  units  called  files.  Whenever  a  program  creates 
a  file,  OS-9  defines  a  portion  of  your  disk  to  store  it.  It  keeps  the 
location  of  the  file  in  a  special  list  (called  a  directory),  also  located 
on  the  disk,  so  that  it  knows  where  to  find  your  program  or  data 
the  next  time  you  want  it. 

About  Directories 

A  directory  is  a  storage  space  for  filenames,  other  directory 
names,  or  both. 

After  you  format  a  disk,  it  contains  one  directory  called  the 
ROOT  directory.  However,  a  disk  can  have  many  directories.  Bbr 
instance,  besides  the  ROOT  directory,  your  System  Master 
diskette  contains  the  CMDS  and  SYS  directories.  The  ROOT  and 
CMDS  directories  are  especially  important  to  you. 

When  you  boot  OS-9,  you  automatically  begin  operation  from 
these  two  directories.  The  ROOT  directory  becomes  your  current 
data  directory  and  the  CMDS  directory  becomes  your  current 
execution  directory. 

Whenever  you  ask  OS-9  to  store  a  file  on  a  diskette,  it  automati- 
cally stores  it  in  the  current  data  directory  (the  ROOT  direc- 
tory), unless  you  tell  it  otherwise.  If  you  ask  OS-9  to  execute  a 
command  or  program,  it  automatically  looks  for  that  command  or 
program  in  the  execution  directory  (the  CMDS  directory),  unless 
you  tell  it  otherwise. 
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Every  OS-9  directory  can  also  contain  other  directories,  called 
subdirectories.  For  instance,  SYS,  and  CMDS  are  established  as 
subdirectories  of  the  ROOT  directory.  Put  in  chart  form,  your 
ROOT  directory  with  its  subdirectories  looks  like  this: 

ROOT  DIRECTORY     


V 
CMDS 


v 
SYS 


Figure  4.1 


But  there  are  also  files  in  the  ROOT  directory,  OS9Boot  and 
Startup  are  two.  The  full  ROOT  directory  might  look  like  this: 

ROOT  DIRECTORY     

i 

OS9Boot 
Startup 


CMDS 


V 
SYS 


Figure  4.2 


You  can  create  another  subdirectory  of  the  ROOT  directory  if  you 
want.  For  instance,  if  you  created  a  directory  named  FAMILY,  the 
chart  of  the  ROOT  directory  looks  like  this: 

ROOT  DIRECTORY  — 

I 

OS9Boot 
Startup 


v 
CMDS 


FAMILY 


v 

SYS 


Figure  4.3 
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After  you  create  the  FAMILY  directory,  you  can  also  create  other 
directories  in  it.  Suppose  you  create  two  subdirectories  named 
PLEASURE  and  WORK.  The  chart  organization  is  as  follows: 

-     ROOT  DIRECTORY     


OS9Boot 

Startup 


V 
CMDS 


f 


FAMILY 


PLEASURE 


1/ 
WORK 


SYS 


Figure  4.4 

The  directories  you  create  also  can  hold  files.  If  you  created  three 
files  each  in  the  PLEASURE  and  WORK  directories,  the  chart 
might  look  like  this: 

—     ROOT  DIRECTORY     

1 

OS9Boot 

Startup 


V 
CMDS 


f 


v 
FAMILY 


PLEASURE 


WORK 


v 

SYS 


i 


mom 
dad 
joe 

Figure  4.5 


mom 
dad 
joe 


You  can  continue  to  create  files  and  subdirectories  in  any  or  all  of 
your  disk's  directories  until  you  fill  the  disk's  storage  space. 
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Multiple  Directories 

There  is  nothing  wrong  with  storing  all  your  files  in  the  ROOT 
directory.  Doing  so  makes  it  easy  to  access  them  because  they  are 
always  in  your  data  directory. 

However,  creating  multiple  directories  makes  it  easy  to  keep  your 
data  organized  when  you  have  many  files,  or  if  more  than  one 
person  is  using  the  same  disk.  Such  a  multiple-directory  organi- 
zation is  especially  helpful  when  using  hard  disks,  which  can 
store  hundreds  of  individual  files. 

Also,  when  you  have  multiple  directories,  you  can  store  files  hav- 
ing the  same  name  in  different  directories  without  conflict,  such 
as  in  the  PLEASURE  and  the  WORK  directories  of  Figure  4.5. 

About  File  and  Directory  Names 

The  file  and  directory  names  shown  so  far  consist  only  of  letters 
of  the  alphabet,  but  you  can  use  other  characters  and  symbols  in 
a  file  or  directory  name  as  long  as  each  name  begins  with  a  let- 
ter. The  following  is  a  complete  list  of  acceptable  characters: 

•  Uppercase  letters:  (A-Z) 

•  Lowercase  letters:  (a-z) 

•  Decimal  digits:  (0-9) 

•  The  underscore  character  (_)  and  the  period  (.) 

"You  can  include  as  many  as  29  characters  in  a  file  or  directory 
name. 

Examples  of  Filenames 

The  following  are  samples  of  filenames  that  OS-9  can  recognize: 


mydata 

samfile 

mydatal 

Dollar-gifts 

records.srt 

help.file 

XXX.xx 

file#l.txt 

progl.bas 

program.sourcecode 

prog2.bas 

program.opcode 
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Examples  of  invalid  filenames  are: 

his*hers    because  *  is  not  a  valid  character  for 

names 
.DATA   because  the  name  does  not  begin  with 

a  letter 
COST  +  INT  because  +  is  not  a  valid  character  for 

names 
100_dollar_gifts  ...because  names  cannot  begin  with  a 

digit 

About  Pathlists 

Because  you  can  organize  OS-9  disks  into  multiple  levels,  you 
need  a  way  to  tell  the  system  where  to  find  directories  and  files. 
The  directions  you  give  are  called  pathlists. 

A  pathlist  is  exactly  what  its  name  implies — a  path  (or  route)  to 
the  device,  directory,  or  file  you  want  to  access.  For  instance,  if 
you  are  in  the  ROOT  directory  (see  Figure  4.5)  and  want  to  look 
at  the  contents  of  a  file  in  the  WORK  directory,  you  must  tell 
OS-9  how  to  get  there.  The  pathlist  from  the  ROOT  directory  to 
the  Dad  file  is  family/work/dad.  OS-9  expects  you  to  separate 
the  junctions  of  pathlists  with  slashes.  To  look  at  the  contents  of 
Dad,  you  type: 


list    family/work /dad  |  ENTER  ] 

Because  you  are  accessing  a  file  on  the  current  disk,  you  do  not 
need  to  specify  a  drive  name.  Because  every  disk  contains  a 
ROOT  directory,  and  all  other  directories  and  files  branch  from  it, 
ROOT  is  always  implied  in  a  pathlist.  If  Figure  4.5  represented 
the  diskette  in  Drive  /Dl,  the  pathname  to  the  Dad  file  would  be 
/d1/famlly/ work/dad. 

Depending  on  the  location  of  the  directory  or  file  you  want  to 
access,  a  full  pathlist  need  not  contain  any  more  than  the  name 
of  a  drive,  the  name  of  a  directory,  or  the  name  of  a  file.  For 
instance,  the  complete  pathlist  from  the  ROOT  directory  of  Fig- 
ure 4.5  to  the  Startup  file  is  startup.  To  look  at  the  contents  of 
Startup,  type: 

list     startup  |  ENTER  I 
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You  already  put  OS-9  to  work  with  commands  such  as  FORMAT 
and  BACKUP,  In  these  cases  the  manual  told  you  exactly  what  to 
do  to  accomplish  a  very  specific  task.  If  you  want  to  strike  out  on 
your  own,   you   should   know  some   additional   background 

information. 

Typing  Commands 

As  explained  earlier,  some  OS-9  files  are  programs.  You  tell  OS-9 
to  execute  these  programs  by  typing  the  program  (file)  name  and 
pressing  (Inter").  You  are  then  issuing  a  command  to  OS-9.  That's 
all  a  command  is,  the  name  of  a  program  for  the  system  to  exe- 
cute. The  following  are  some  rules  about  commands: 

•  You  can  enter  a  command  whenever  the  screen  displays 
the  system  prompt  (DS9:). 

•  A  command  consists  of  one  word,  the  command  name.  A 
command  line  consists  of  one  or  more  command  names 
and  their  associated  parameters  and  modifiers.  Parame- 
ters and  modifiers  are  special  information  you  include 
with  a  command  that  provide  necessary  data  for  the  com- 
mand to  operate,  or  that  affect  the  command's  operation. 

•  A  command  line  can  have  a  maximum  of  198  characters 
including  any  combination  of  upper-  or  lowercase  letters. 
To  execute  a  command,  press  1  enter  ).  For  example,  to  clear 
the  screen,  type: 


display    0c  |  ENTER  | 

Editing  Commands 

OS-9  is  very  particular  about  the  commands  you  type.  If  you 
make  any  mistake,  OS-9  either  does  not  understand  (and  tells  you 
so  with  an  error  message)  or  does  the  wrong  thing, 

If  you  see  that  you  made  a  mistake  before  you  press  (  enter  1,  you 
have  two  choices:  (1)  use  Q  or  (cTflTI  QQ  to  move  the  cursor  to  the 
mistake,  and  retype  that  portion  of  the  line,  or  (2)  press  [ctrl!  (T| 
or  |  shift  1  @  to  erase  the  line  you  are  typing,  and  start  over. 
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Command  Parameters 

You  can  follow  a  command  name  with  one  or  more  parameters 
that  give  OS-9  more  specific  instructions.  For  example,  in  the 
command  line: 


list     filel     ENTER 


LIST  is  the  name  of  the  command  that  displays  the  contents  of  a 
text  file.  Filel,  the  specified  parameter,  is  the  name  of  the  file 
that  you  want  displayed. 

Note:  In  a  command  line,  always  use  spaces  to  separate 
parameters  from  their  command,  and  from  each  other. 
Parameters  cannot  contain  spaces.  Chapter  6  discusses 
parameters  for  each  OS-9  command. 

Some  commands  have  more  than  one  parameter.  For  instance, 
COPY  requires  two  parameters;  the  name  of  the  file  being  cop- 
ied, and  the  name  of  the  new  file  you  want  COPY  to  create.  If  you 
want  to  copy  a  file  called  Startup,  and  call  the  copy  Newstartup, 
your  command  line  reads: 

__ COPY,  the  command 


name. 


V 


The  name  of  the  file 
to  copy 

The  name  of  the  copy 


v 


You  press  I  enter  [  to 
cause  the  command 
line  to  execute. 


copy    startup   newstartup 


ENTER 


Using  Options 

Command  lines  can  also  contain  another  type  of  parameter,  called 
an  option.  An  option  changes  the  way  a  command  performs.  For 
instance,  the  command  DDR,  without  parameters,  shows  the  name 
of  all  files  in  the  current  data  directory. 
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However,  if  you  add  the  E  option  as  a  parameter  to  the  com- 
mand, like  this: 


dire  I  ENTER  I 


the  output  includes  not  only  the  names  of  the  files,  but  also  com- 
plete statistics  about  each  file— the  date  and  time  created,  size, 
security  codes,  and  so  forth. 

To  display  complete  information  about  each  file  in  SYS,  type: 


dir    ays     e  |  ENTER  | 

Using  Commands 

As  described  in  Part  1,  OS-9  acts  in  much  the  same  manner  as 
an  office  manager.  It  looks  after  the  operation  of  your  computer 
and  equipment.  Because  OS-9  is  only  a  manager,  it  expects  you  to 

make  the  necessary  decisions. 

Ear  example,  suppose  you  have  an  important  file  named  Hotstuff 
that  you  want  to  copy.  Before  giving  it  to  your  office  manager 
(OS-9),  you  must  make  executive  decisions,  such  as: 

•  Do  you  want  the  copy  on  disk,  paper,  or  the  computer 
screen? 

•  If  you  want  the  copy  on  disk,  which  disk? 

•  If  you  want  the  copy  on  the  same  disk,  what  name  do  you 
want  to  give  the  second  copy  so  OS-9  is  not  confused? 

•  If  you  want  the  copy  on  the  computer  screen,  do  you  want 
the  display  to  pause  when  it  fills  the  screen? 

You  make  the  decisions,  OS-9  manages  the  job.  Fbr  instance,  if 
your  decision  is  to  copy  Hotstuff  from  one  diskette  to  to  another, 
you  might  type  the  following  command  line: 


copy    /d0/hotstuff    /d1  /hotcopy  |  ENTTR  | 
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This  is  how  OS-9  sees  your  command: 


V       V 


r 


The  name  of  the 
command 

The  disk  drive 
containing  the  file  to  be 
copied 

The  name  of  the  file  to 
copy 

The  disk  drive  that  is  to 
receive  the  new  file 


The  name  of  the  copy 


copy  /dfl/hot stuff  /d1 /hotcopy 

This  command  line  tells  OS-9  to  copy  a  file  named  Hotstuff  from 
your  floppy  disk  Drive  /DO  to  a  second  floppy  Drive  /Dl.  The  file 
copy  is  given  the  new  name,  Hotcopy. 

You.  only  need  to  know  the  name  of  the  file  you  want  to  copy,  on 
which  disk  it  is  located,  and  the  disk  on  which  you  want  the  new 
copy.  OS-9  manages  the  operation  for  you. 

Accessing  Commands 

OS-9  has  two  ways  to  access  commands.  Some  commands  reside 
on  a  disk.  When  you  type  the  command  name  and  press  |  enter  |, 
OS-9  must  look  on  the  disk,  load  the  program  into  the  comput- 
er's memory,  and  then  execute  it. 

Other  commands  are  loaded  into  your  computer's  memory  at 
startup,  or  you  can  bad  them  into  memory  later.  When  you  call 
a  command  that  is  in  memory,  it  is  executed  immediately.  There 
is  no  delay  while  OS-9  finds  it  on  disk. 
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Commands  from  Disk 

When  you  give  OS-9  a  command  that  it  cannot  find  in  memory,  it 
looks  for  the  command  in  the  current  execution  directory.  If  it 
cannot  find  it  there,  it  checks  the  current  data  directory.  If  it  still 
cannot  find  it,  the  system  issues  Error  Message  #216,  Path  Name 
Not  Found.  If  the  command  you  want  executed  is  in  a  directory 
other  than  the  current  directory,  you  must  tell  OS-9  where  to  find 
it.  Remember,  when  initialized,  OS-9  sets  the  CMDS  directory  of 
the  system  disk  to  be  the  execution  directory. 

For  instance,  suppose  you  booted  your  system  using  a  diskette 
configured  like  the  example  we  used  in  Chapter  4: 

ROOT  DIRECTORY  


I 


v 


OS9Boot 

Startup 


CMDS  _FAMILy  SYS 


r    i 


PLEASURE 

1 

WORK 

1 

mom 
dad 

joe 

mom 
dad 
joe 
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When  the  system  starts,  the  ROOT  directory  is  the  data  direc- 
tory, and  the  CMDS  directory  is  the  execution  directory.  Now, 
suppose  you  had  a  program  named  Expenses  in  the  family 
directory: 

ROOT  DIRECTORY  


CMDS 


I 


OS9Boot 

Startup 


-FAMILY  — , 


V 

SYS 


expenses 


PLEASURE 


1 


WORK 


I 


mom 
dad 
joe 


mom 
dad 
joe 


(Remember  that  a  program  and  a  command  are  really  the  same 
thing.) 

You  can  now  access  (use)  the  expenses  program  in  two  ways.  One 
way  is  to  specify  a  pathlist  from  the  ROOT  directory  to  execute 
Expenses,  such  as: 


/dB/family/expensea  [ ENTER  | 
Another  way  is  to  change  the  execution  directory. 

Changing  the  Execution  Directory 

To  change  the  execution  directory  to  the  FAMILY  directory,  type: 


chx    /da/family  j  ENTER  | 

Or  specify  a  pathlist  relative  to  the  current  execution  directory, 
such  as: 


chx     .  ./family  [ENTER  | 

To  execute  the  Expenses  program,  you  now  only  need  to  type 

expenses  I  ENTER  |. 
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However,  after  you  change  the  execution  directory,  to  use  a  com- 
mand in  the  COMMANDS  directory,  you  must  tell  OS-9  where  to 
find  it.  For  example,  to  format  a  new  diskette  in  Drive  /Dl,  type: 

/d0/cmds/format    /d1 

Changing  the  Data  Directory 

Suppose  that  the  Expenses  program  keeps  track  of  work  and 
pleasure  expenses  for  Mom,  Dad,  and  Joe.  Unless  you  tell  OS-9 
otherwise,  it  looks  for  data  files  in  the  current  data  directory,  the 
ROOT  directory.  To  tell  OS-9  to  look  for  data  files  in  the  PLEA- 
SURE directory,  type: 

ohd    family/pleasure  [ENTER! 

The  slash  between  FAMILY  and  PLEASURE  tells  the  system  that 
PLEASURE  is  a  branch  of  FAMILY.  Subordinate  directories  and 
files  are  always  separated  from  their  parent  in  this  way. 

Now,  when  Expenses  needs  data,  it  knows  to  look  in  the  PLEA- 
SURE directory. 

Changing  System  Diskettes 

Although  it  is  preferable  to  leave  the  system  diskette  in  place 
while  the  system  is  running,  particularly  with  multiuser  sys- 
tems, there  might  be  times  when  you  need  to  use  another 
diskette.  Only  remove  the  current  diskette  when  the  screen  dis- 
plays the  OS-9  prompt,  followed  by  the  cursor.  If  you  do  remove 
the  system  diskette  and  begin  to  use  another  one,  use  the  CHD 
and  CHX  commands  to  tell  OS-9  where  you  want  to  be  located  on 
the  new  diskette.  (For  directions,  see  Chapters  2  and  6.)  Those 
commands  set  both  directory  pointers,  data  and  execution,  for  the 
new  diskette. 

While  using  a  program  or  command,  do  not  remove  a  diskette  and 
insert  another  unless  the  program  or  command  asks  you  to.  You 
can  lose  data,  or  entire  files,  if  you  do. 
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Video  Display  and  Keyboard  Functions 

OS-9  has  many  features  that  expand  the  capability  of  the  Color 
Computer's  video  display  and  keyboard. 

•  The  video  display  has  upper-/lowercase,  screen  pause, 
graphics  functions,  and  80  column  displays  if  you  have  a 
monitor  connected. 

•  The  I  alt  |  key  provides  an  alternate  key  function.  Holding 
down  |  alt  |  while  pressing  another  key  sets  the  high  order 
bit  of  the  character  pressed.  That  is,  it  adds  128  to  the 
normal  ASCII  value  produced  by  that  key.  Holding  down 
I  alt  |  while  pressing  any  other  key  produces  a  graphics 
character  on  the  standard  VDG  screen.  If  you  are  using 
windows,  |  alt  ]  lets  you  produce  international  characters. 
(See  OS-9  Windowing  System  Owner's  Manual  for  more 
information). 

•  The  keyboard  has  an  auto-repeat  function.  Holding  down 
a  key  causes  the  character  to  repeat  until  you  release  the 
key.  This  function  operates  properly  only  when  the  disk 
drives  are  not  in  use  by  a  program. 

•  'You  can  deal  with  the  video  display  and  keyboard  together 
as  though  they  are  a  file.  You  can  receive  input  from  the 
keyboard  and  send  output  to  the  video  screen  using  the 
device  name  /TERM. 


Special  Keys 

The  following  keys  and  key  sequences  have  special  significance  to 
OS-9. 

I  alt  |  Produces  graphic  characters  on  a  stan- 

dard VDG  screen  or  international 
characters  with  windows.  Press  |alt| 
char  where  char  is  a  keyboard  charac- 
ter). 

A  control  key. 

Stops  the  current  program  execution. 


|  CTRL  | 

|  BREAK  |  or 

1  CTRL  ||  E  | 

Qor 

1  CTRL  ||  H  | 

Moves  the  cursor  to  the  left  one  space. 
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1  CTRL  |[-! 

1  CTRL  II- 1 

1  CTRL  ||. I 

1  CTRL  ||  3  | 

1  CTRL  ||  / 1 

|  CTRL  ||  BREAK  ) 

or  |  CTRL  ||  C  | 

|  SHIFT  ||  BREAK  | 

|  CLEAR  |* 

|  SHIFT  ||  CLEAR  | 

CTRL     CLEAR 


SHIFT 


■or 


CTRL    X 


CTRL     0 


CTRL     1 


rcTRurn 


CTRL    8 


Generates  an  underscore  character.  The 
underscore  displays  as  a  left  arrow. 

Generates  a  left  brace  ({). 

Generates  a  right  brace  (}). 

Generates  a  tilde  (~). 

Generates  a  backslash  (  \  ). 

Performs  an  ESCAPE  function,  and 
sends  an  end-of-file  message  to  a  pro- 
gram receiving  keyboard  input.  To  be 
recognized,  [  ctrl  ||  break  |  must  be  the 
first  thing  typed  on  a  line. 

Performs  a  CONTROL  C  function  by 

interrupting  the  video  display  of  a  pro- 
gram. The  program  runs  as  a  back- 
ground task. 

Selects  the  next  video  window, 

Selects  the  previous  video  window, 

*  You  must  have  established  windows 
for  this  function  key  to  have  any 
effect.  See  "Using  Windows"  in 
Chapter  7. 

Toggles  the  keyboard  mouse  on  and  off. 
The  keyboard  mouse  uses  the  arrow 
keys  and  the  two  function  keys  {Fl  and 
F2)  to  simulate  an  external  mouse. 
When  keyboard  mouse  is  on,  the  nor- 
mal functions  for  the  arrow  and  func- 
tion keys  is  suspended. 

Deletes  the  current  line. 


Activates  or  deactivates  the  shift  lock 
function. 

Generates  a  vertical  bar  (|). 

Generates  an  up  arrow  (4). 

Generates  a  left  bracket  ([). 
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I  ctrl  inn  Generates  a  right  bracket  ( ] ), 

I  gtrl  |fXl  Redisplays  the  last  line  you  typed  and 

positions  the  cursor  at  the  end  of  the 
line,  but  does  not  process  the  line. 
Press  |  enter  |  to  process  the  line,  or  edit 
the  line  by  backspacing.  If  you  edit, 
press  |  CTRt  ||T|  again  to  display  the 
edited  line. 

1  CTRL  |pD  Redisplays  the  current  command  line. 

I  ctrl  ||"w"l  Temporarily  halts  video  output.  Press 

any  key  to  resume  output. 

I  enter  |  Performs  a  carriage  return  or  executes 

the  current  command  line. 
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You  now  know  about  a  number  of  OS-9  commands  that  can  help 
you  set  up  and  use  your  computer  system.  There  are  many  more 
commands  available.  This  chapter  contains  information  about  a 
few  of  the  most  helpful  commands.  Becoming  acquainted  with 
these  makes  it  easy  for  you  to  use  other  commands  and  func- 
tions. OS-9  Commands  contains  more  information  and  a  com- 
plete reference  to  all  OS-9  commands  (including  those  you  have 
already  discussed). 

Viewing  Directories 

To  look  at  your  disk  directories  use  the  DIR  command.  For  exam- 
ple, to  view  the  contents  of  the  current  data  directory,  type: 


dir  I  ENTER  I 


If  your  data  directory  contains  more  filenames  than  can  display 
on  the  screen  at  one  time,  the  display  pauses.  Press  the  space  bar 
to  cause  additional  files  to  scroll  onto  the  screen. 

You  can  also  view  your  execution  directory  in  a  similar  manner. 
This  time  you  must  include  the  command  option,  x.  Type: 


dir    x  I  ENTER  I 


If  you  want  to  look  at  a  directory  on  a  disk  drive  other  than  the 
current  drive,  specify  a  complete  path  for  OS-9  to  follow,  includ- 
ing the  disk  drive  name.  For  example: 


dir     /d0/FAMiLY/WORK  (ENTER  I 


Creating  Directories 

Before  you  can  store  data  in  a  directory  other  than  the  ROOT 
directory,  you  must  create  that  directory  with  MAKDIR.  For 
instance,  to  create  a  FAMILY  directory  on  your  Drive  /DO 

diskette,  type; 


makdir    /d0/FAMILY  I  ENTER  I 
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Deleting  Directories 

You  can  also  delete  directories  you  create.  When  you  delete  a 
directory  you  also  delete  any  files  or  subdirectories  it  con- 
tains; so  use  this  command  with  caution.  To  delete  a  direc- 
tory, follow  these  steps. 

1.  Use  DIR  to  view  the  contents  of  the  target  directory  and  any  of 
its  subdirectories. 

2.  Copy  any  files  you  want  to  keep  into  a  directory  outside  of  the 
directory  you  want  to  delete. 

3.  Type: 


deldir    dlrname  I  ENTER  I 


where  dirname  is  the  name  of  the  directory  you  want  to  delete. 

The  screen  shows: 

Deleting  directory  file. 

List  directory,  delete  directory,  or  quit  ? 

(1/d/qJ 

4.  You  now  have  three  options: 

a.  To  again  confirm  the  contents  of  the  directory  before  you 
delete  it,  press  0  |  enter  |. 

b.  To  initiate  the  deletion  process,  press  |T|  |  enter  |. 

c.  To  quit  the  process  and  leave  the  directory  intact,  press  Q] 
("Inter"!. 

If  you  try  to  delete  directories  other  than  the  ones  you  create, 
OS-9  might  display  Error  #214,  No  Permission  (you  do  not  own 
the  directory  or  have  write  permission  for  it).  For  information  on 
handling  such  directories,  see  the  ATTR  command  in  OS-9 
Commands, 

Displaying  Current  Directories 

There  are  times  when  you  need  to  know  the  names  of  your  cur- 
rent data  and  execution  directories.  The  PWD  and  PXD  com- 
mands make  this  possible.  To  determine  your  current  data 
directory,  type: 


pwd  |  ENTER  | 
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The  command  displays  the  path  from  the  ROOT  directory  to  the 

current  data  directory.  For  instance,  if  your  current  data  direc- 
tory is  PLEASURE  (see  Figure  4.5  in  Chapter  4)  the  display  is: 

/D0/FAMILY/PLEASURE 

To  discover  your  current  execution  directory,  type: 


pxd  I  ENTER  | 

The  screen  might  display: 

/D0/CMDS 

A  standard  convention  of  OS-9  is  to  capitalize  directory  names.  If 
you  follow  this  convention  when  creating  directories,  you  can 
always  tell  which  files  are  directories  at  a  glance. 

Copying  Files 

COPY,  like  BACKUP,  provides  file  security.  If  something  hap- 
pens to  one  file,  you  can  use  a  copy.  Also,  you  might  want  to  copy 
a  command  or  program  to  use  in  more  than  one  directory,  or  you 
might  want  to  use  the  same  data  on  more  than  one  computer. 

Suppose  you  are  in  the  PLEASURE  directory  of  a  diskette  confi- 
gured as  in  Figure  4.5.  Your  execution  directory  is  the  FAMILY 
directory,  where  you  are  using  the  Expenses  program.  Because 
the  FAMILY  directory  does  not  contain  any  OS-9  commands,  you 
have  to  change  the  execution  directories  whenever  you  want  to  use 
them. 

You  can  make  your  work  easier  by  copying  the  Expenses  pro- 
gram to  the  CMDS  directory.  To  do  this,  first  make  the  CMDS 
directory  your  data  directory  by  typing: 


chd    /d0/CMDS  I  ENTER  | 

Then  copy  the  Expenses  file  to  the  CMDS  directory  by  typing: 

copy    /d8/FAMILY/expenses    expenses  [ENTER] 

Now,  Expenses  is  in  the  CMDS  directory,  and  you  do  not  need  to 
change  the  execution  directory  to  FAMILY  to  use  it. 
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Likewise,  if  the  ROOT  directory  is  your  data  directory,  and  you 
want  to  copy  the  Mom  file  from  the  WORK  directory  to  the  ROOT 
directory,  type: 


copy  f ami ly/wor k /mom  mom  |  ENTER) 

You  can  copy  any  file  between  directories  and  between  disks.  To 
do  so,  you  must  provide  the  COPY  command  with  a  pathlist  for 
the  location  of  the  original  file  and  for  the  destination  of  its  copy. 

Deleting  Files 

You  can  delete  files  in  any  directory  using  the  DEL  command, 
such  as: 


del    myf  ile  [  ENTER  | 

You  can  delete  a  file  in  the  current  execution  directory  by  using 
the  —x  parameter.  For  instance,  to  delete  Myprogram  from  the 
current  execution  directory,  type: 


del     -x    myprogram  fENTER  1 

If  the  file  you  want  to  delete  is  in  a  directory  other  than  the  cur- 
rent data  directory  or  the  current  execution  directory,  you  must 
specify  the  full  pathlist  to  the  file.  For  instance,  suppose  you  are 
in  the  ROOT  directory  of  a  diskette  configured  as  Figure  4.5.  To 
delete  the  Joe  file  in  the  WORK  directory,  type: 


del    family/work/]  oe  I  ENTER  | 

If  the  file  you  want  to  delete  is  on  a  drive  other  than  your  cur- 
rent drive,  include  the  drive  name  in  your  pathlist,  such  as: 


del    /d1  /  f  ami  ly/wor  k/joe  I  ENTER  [ 

If  you  attempt  to  delete  a  file  you  did  not  create,  OS-9  might  dis- 
play Error  #214,  No  Permission.  For  information  on  deleting  such 
files  see  the  ATTR  command  in  OS-9  Commands, 


Renaming  Files 

OS-9  lets  you  change  the  names  of  files.  Suppose  Joe  leaves  home, 
and  you  now  want  to  keep  track  of  expenses  for  Sue.  To  change 
the  name  of  the  Joe  file  to  Sue,  type: 


rename    f amily/plea5ure/ j oe      sue  [  ENTER) 
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Looking  Inside  Files 

LIST  is  a  command  that  lets  you  examine  files  that  consist  of  text 
characters.  For  instance,  to  view  the  Dad  file  from  the  WORK 
directory,  you  might  type: 


list    fami  ly /work /dad  [ENTEHj 

The  contents  of  the  file  appears  on  the  screen. 

If  you  use  LIST  to  display  a  file  that  is  not  a  text  file,  it  pro- 
duces a  meaningless  display. 

Loading  Command  Modules  into  Memory 

When  using  OS-9,  you  might  notice  that  some  commands  begin 
execution  immediately,  while  others  require  access  to  the  disk 
drive  before  they  execute.  The  OS-9  commands  you  need  most 
often  load  into  memory  at  startup,  so  they  are  available  for 
immediate  use.  If  you  plan  to  frequently  use  a  command  that  is 
not  in  memory,  you  can  had  it. 

For  instance,  the  DSAVE  command  lets  you  copy  an  entire  direc- 
tory from  one  disk  to  another.  To  place  the  DSAVE  module  into 
your  computer's  memory,  first  be  sure  your  execution  directory  is 
the  CMDS  directory,  then  type: 


load    danve  I  ENTEfl  I 


Now  you  can  use  DSAVE  as  many  times  as  you  want,  without 
waiting  for  OS-9  to  find  it  on  disk. 

Listing  the  Command  Modules  in  Memory 

At  startup,  OS-9  loads  into  memory  the  commands  you  use  most 
often.  If  you  are  not  sure  whether  a  command  already  resides  in 
memory,  you  can  check  using  the  MDIR  command.  To  display  a 
directory  of  the  modules  in  your  computer's  memory,  type: 


mdir  I  ENTER  I 


A  list  of  all  the  modules  in  your  computer's  memory  appear  on 
the  screen.  The  names  you  see  are  of  modules  OS-9  uses  to  boot 
and  handle  system  operations  and  the  commands  it  loads  into 
memory  when  you  boot  the  system. 
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Deleting  Modules  from  Memory 

After  you  load  a  module  into  memory,  you  can  also  delete  it.  The 
process  is  called  unlinking.  To  delete  the  DSAVE  command  from 
memory,  type: 


unlink    DSAVE  |ehTer| 

Do  not  attempt  to  unlink  modules  that  you  did  not  install  in 
memory  with  the  LOAD  command. 

Using  Other  Commands 

OS-9  has  nearly  50  commands  and  functions.  This  chapter  has 
mentioned  only  a  few.  Not  only  are  there  other  commands  avail- 
able through  OS-9,  several  of  the  commands  presented  here  have 
additional  options. 

The  guidelines  you  learned  in  this  handbook  provide  the  back- 
ground you  need  to  make  use  of  OS-9's  many  other  capabilities. 

By  referring  to  GS-9  Commands  you  can  learn  how  to  create  files, 
create  procedure  files  to  accomplish  complicated  tasks,  send 
information  to  your  printer,  transfer  data  between  devices,  exe- 
cute more  than  one  task  at  the  same  time,  and  much  more. 
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'feur  OS-9  operating  system  is  originally  configured  in  a  certain 
way.  For  instance,  it  is  set  up  to  recognize  two  floppy  disk  drives, 
but  no  hard  drives.  It  is  set  up  to  recognize  a  printer  or  one  extra 
terminal.  It  does  not  recognize  a  modem.  It  assumes  that  you  only 
want  32  characters  across  your  computer's  display  screen.  It  pro- 
vides all  of  the  OS-9  commands. 

Using  the  CONFIG  utility  from  the  BASIC09/CONFIG  diskette 
that  came  with  your  OS-9  package,  you  can  create  system 

diskettes  that  match  the  computer  system  you  have.  Before  pro- 
ceeding further,  be  sure  you  have  a  working  copy  of  the  BASIC09/ 
CONFIG  diskette  and  a  blank,  formatted  diskette.  %u  can  use 
the  instructions  in  "Making  Copies  of  Diskettes"  in  Chapter  3  to 
create  a  working  copy  of  the  BASIC09/CONFIG  diskette  and  to 
create  a  blank,  formatted  diskette. 

Creating  a  New  System  Diskette 

To  create  a  new  system  diskette  make  sure  you  have  a  newly 
formatted  diskette  on  hand,  then  follow  these  steps: 

1.  Take  out  the  System  Master  diskette,  and  replace  it  with  the 
BASIC09/CONFIG  diskette.  Type: 


chx    /d0/cmdH  [  ENTER  I 


chd    /d0  I  ENTER  I 


conf  ig  |  ENTER  | 

The  first  question  the  screen  asks  is: 

HOW   MANY   DRIVES   DO    YOU   HAVE: 

1  -    ONE   DRIVE    ONLY 

2  -    TWO   OR   MORE   DRIVES 

SELECTION    [1 ,21 

2.  If  you're  using  a  single-drive  system,  press  (TJ.  If  you  have 
more  than  one  drive,  press  |T|. 

If  you  indicated  that  you  have  two  or  more  drives,  CONFIG 
prompts: 

Enter  Name  of  Source  Disk; 
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and 

Enter  Name  of  Deat.  Disk: 

Type  the  appropriate  drive  name  (/DO,  /Dl,  etc.)  at  each 
prompt. 

3.  OS-9  informs  you  that  it  is: 


BUILDING  DESCRIPTOR  LIST 
PLEASE  WAIT 


OS-9  is  putting  together  a  list  of  the  various  devices  you 
might  want  to  use  with  your  computer.  When  it  finishes,  it 

shows  you  the  list: 


CDNFIG 
ARROWS    -    UP/DOWN/MORE/BACK 
S    -    SEL/UNSEL    H    -    HELP   D   -    DONE 
ITEM  SEL 

-*•  P 
T1 
T2 
T3 
M1 
M2 

PIPE 

D0_35a        X 
D1_35s 
D2_3Ss 
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To  view  the  rest  of  this  menu,  press  Q.  Now  the  screen 
shows: 

CONFIG 

ARROWS    -    UP/DQWN/MDRE/BACK 
S    -    SEL/UNSEL    H    -    HELP   D    -    DONE 
ITEM  SEL 


-*■       D3_35s 

ddd0_35s 

D0_40D 

D1_40D 

D2_4  0D 

DDD0_4  0D 

D1-80D 

D2_80D 

4.  You  can  choose  the  various  devices  you  plan  to  use  with  your 
computer  from  this  list.  To  choose  a  device,  use  m  or  m  to 
move  to  the  device.  The  -*■  shows  the  device  you've  chosen. 
Then,  press  GO  (for  Select)  to  display  an  X  in  the  SEL 
("Selected")  column.  Pressing  (T)  again  cancels  the  selection. 

You  can  move  back  and  forth  between  the  first  and  second 
screens  by  pressing  either  Q  (from  the  first  screen)  or  @ 
(from  the  second  screen).  Here's  a  short  description  of  each 
device  listed  on  this  screen.  To  display  helpful  information 
about  a  device,  position  the  -*■  on  its  line  in  the  list,  and  press 
QT)  for  Help.  Then,  press  the  space  bar  to  make  the  help 
information  disappear.  The  devices  on  this  screen  are: 

P  A  printer  that  connects  to  the  RS-232  serial  port 

on  your  computer. 

Tl  A  terminal  using  the  standard  RS-232  port  (in 

addition  to  your  main  computer  display). 

T2  A  terminal  using  the  optional  RS-232  commu- 

nications pak  in  Slot  1  of  the  Multi-pak  Inter- 
face, T2  supports  a  full  baud  rate  range.  Use  T2 
in  addition  to  your  main  computer  display  alone, 
or  in  addition  to  your  main  computer  display  and 
a  'Tl"  type  terminal. 
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T3  Another  terminal  using  the  optional  RS-232 

communications  pak  in  Slot  2  of  the  Multi-pak 
Interface. 

Ml  A  modem  using  an  optional  300  baud  modem 

pak. 

M2  A  modem  using  an  optional  300  baud  modem 

pak. 

PIPE  Lets  you  use  the  PIPE  utility  in  OS-9  (a  utility 

that  takes  the  information  a  program  puts  out 
and  uses  it  as  input  data  in  another  command). 

D0_35S  Floppy  Disk  Drive  /DO,  single  sided,  35  tracks. 

D1_35S  Floppy  Disk  Drive  /Dl,  single  sided,  35  tracks. 

D2_35S  Floppy  Disk  Drive  /D2,  single  sided,  35  tracks. 

D3-35S  Floppy  Disk  Drive  /D3,  single  sided,  35  tracks. 

DDD0_35S  Default  Disk  Drive  /DD  using  Drive  /DO,  single 
sided,  35  tracks.  Select  one  default  drive  —  the 
drive  where  you  keep  your  system  diskette. 

D0_40D  Floppy  Disk  Drive  /DO,  double  sided,  40 
cylinders. 

D1_40D  Floppy  Disk  Drive  /Dl,  double  sided,  40 
cylinders. 

D2_40D  Floppy  Disk  Drive  /D2,  double  sided,  40 
cylinders. 

D3_40D  Floppy  Disk  Drive  /D3,  double  sided,  40 
cylinders. 

DDD0-40D  Default  Disk  Drive  /DD  using  Drive  /DO,  double 
sided,  40  cylinders.  Select  one  default  drive  — 
the  drive  where  you  keep  your  system  diskette. 

D1_80D  Floppy  Disk  Drive  /Dl,  double  sided,  80 
cylinders. 

D2_80D  Floppy  Disk  Drive  /D2,  double  sided,  80 
cylinders. 
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You  must  select  a  "DO"  device  as  your  first  disk  drive— use 
Dl,  D2,  and  D3  devices  for  additional  floppy  disk  drives.  Select 
the  drive  that  matches  the  drives  you  have  on  your  system.  If 
you  are  not  sure,  check  with  your  supplier.  To  use  extra  ter- 
minals and  modems,  you  must  connect  them  via  a  Multi-Pak 
Interface. 

5.  As  you  finish  choosing  among  the  devices  on  the  first  screen, 
press  (3  to  display  another  screen  of  devices: 

6.  When  you  finish  selecting  devices,  press  QT)  for  Done.  The 
screen  asks: 

ARE  YDU  SURE  (Y/N>  ? 

7.  Nows  your  chance  to  change  your  mind.  Press  (¥)  if  you  want 
to  reselect  your  devices.  If  you're  sure  about  the  devices  you 
selected,  press  (T). 

The  next  part  of  the  CONFIG  process  appears  on  the  screen: 

CONFIG 

SELECT   TERM   DESCRIPTOR 

1  -   TERM_VDG 

2  -    TERM-WIN 

H    -    HELP 
SELECTION    C1 ,23 

8.  These  are  Color  Computer  terminal  I/O  subroutine  modules 
you  can  use.  For  a  32  character  display,  select  1  (TERM- 
VDG).  In  order  to  have  OS-9  windows  and  an  80  column  dis- 
play, select  2  (TERM- WIN). 

Note:  You  can  use  TERM. WIN  with  a  TV  rather  than 
a  monitor  but  it  is  difficult,  if  not  impossible,  to  see 
characters  on  an  80-column  window.  When  you  later 
create  text  windows,  select  40-column  displays. 
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If  you  select  2  (Term_Win),  CONFIG  presents  you  with 
another  menu  of  choices.  This  time,  the  display  looks  like  this: 

CONFIG 

ARROWS    -    UP/DOWN/MORE/BACK 
S    -    SEL/UNSEL    H    -    HELP   D   -   DONE 
ITEM  SEL 


w 

X 

W1 

X 

W2 

X 

W3 

W4 

W5 

W6 

W7 

This  list  represents  the  pre-established  windows  you  can  open 
for  use  with  OS-9.  The  next  section  in  this  chapter  tells  you 
how  to  open  and  use  windows.  For  now,  if  you  expect  to  open 
windows  in  which  you  can  run  mulitple  tasks,  select  these 
items  for  your  new  diskette.  (See  "Using  Windows"  later  in 
this  Chapter.) 

9.  After  you  select  the  modules  you  want  to  use,  press  [T).  As  it 
did  when  you  selected  devices,  the  screen  asks  ARE  you  sure 
cy/N)  ?  Press  (T)  if  you're  finished.  Or,  press  (¥)  to  keep 
working  on  this  screen. 

OS-9  creates  a  file  called  Bootlist  in  Drive  /DO's  ROOT 
directory,  using  the  information  you've  provided  so  far.  It  lets 

you  know  what  it's  up  to  by  displaying: 

BUILDING  BOOT  LIST 
PLEASE  WAIT 

Then,  the  screen  asks: 

WHAT  CLOCK  MDDULE  IS  NEEDED: 

1  -  60  HZ  (AMERICAN  POWER) 

2  -  50  HZ  (EUROPEAN  POWER) 

10.  Press  (T)  if  you  live  in  the  United  States,  Canada,  or  any 
other  country  that  uses  60Hz  electrical  power.  If  you  live  in  a 
country  that  uses  50Hz  electrical  power,  press  fJJ, 
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11.  CONFIG  is  ready  to  begin  creating  your  customized  System 
Master  diskette,  If  you  have  one  drive,  the  screen  tells  you 
that  the  DESTINATION  diskette  is  your  blank,  formatted 
diskette  and  that  your  SOURCE  diskette  is  the  BASIC09/ 
CONFIG  diskette.  Place  your  formatted  diskette  in  the  drive, 
and  press  (T|-  Yoxi'll  swap  between  the  formatted  diskette  and 
the  BASIC09/CONFIG  diskette  several  times. 

If  you  have  a  two-drive  system,  place  a  formatted  diskette  in 
Drive  /Dl,  and  press  the  space  bar.  The  screen  tells  you  that 
OS-9  is: 

GENERATING  A  NEW  BOOT 
PLEASE  WAIT 

12.  Following  the  boot  file  generation,  a  menu  lets  you  select  the 
commands  you  want  to  include  on  your  system  diskette.  Y>u 
have  the  following  choices:  none;  a  basic,  limited  set  of  com- 
mands; the  full  set  of  commands;  or  a  set  consisting  of  com- 
mands you  choose  individually.  The  menu  looks  like  this: 

CONFIG 

DO   YOU   WISH   TO   ADD 
[NIO    COMMANDS,    STOP   NOW 
[B3ASIC   COMMAND   SET 
[F3ULL    COMMAND    SET 
II  INDIVIDUALLY    SELECT 
[?]    RECEIVE   HELP 
SELECTION    tN.B.F.I,?] 

A  basic  command  set  does  not  include: 

•  The  OS-9  Macro  Edit  module 

•  System  maintenance  commands  such  as  DSAVE, 
DCHECK,  and  COBBLER 

Most  people  like  to  choose  the  individual  commands  they  want 
to  use.  For  the  time  being,  press  (T)  to  include  the  full-  set. 
Later,  you  can  create  another  custom  diskette  that  has  only 
the  commands  you  need. 
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13.  Do  one  of  the  following: 

a.  If  you  have  one  drive,  the  screen  asks  you  to  place  your 
formatted  diskette  in  Drive  /DO.  Do  so,  and  press  the  space 
bar.  Next,  you'll  place  your  "uncustomized"  backup  of  the 
System  Master  diskette  in  Drive  /DO.  Swap  the  two 
diskettes  as  the  screen  asks  you  to.  When  the  CONFIG 
program  finishes,  the  DS9:  message  reappears.  %u  now 
have  a  brand  new,  customized  copy  of  the  System  Master 
diskette. 

b.  If  you  have  more  than  one  drive,  CONFIG  continues  and  in 
a  few  minutes,  finishes  its  work.  The  0S9:  message  reap- 
pears, and  you  have  a  customized  copy  of  the  System  Mas- 
ter diskette  in  Drive  /Dl. 

14.  Label  the  diskette  so  that  you  can  distinguish  between  your 
working  copy  of  the  System  Master  diskette  and  the  custom 
copy. 

Monitor  Types 

OS-9  lets  you  set  your  system  for  different  monitor  types.  The 
monitor  options  are  for  a  RGB  color  monitor,  a  composite  color 
monitor  or  TV,  or  a  monochrome  monitor  or  TV.  To  set  your  sys- 
tem for  a  particular  monitor  type,  enter  one  of  the  following  com- 
mands, or  add  it  to  your  system  Startup  file: 

Monitor  Type Command 

RGB  montype  r 

Composite  montype  c 

Monochrome  montype  m 

Therefore,  to  set  your  system  for  a  composite  monitor,  type: 


montype    c  |  ENTER  | 

To  save  typing  the  command  each  time  you  start  OS-9,  put  it  in 

the  Startup  file  in  the  ROOT  directory  of  your  system  diskette. 

If  your  system  disk  does  not  have  an  existing  Startup  file: 

Create  one  by  typing; 

build    startup  [TntER] 
montype    r  |  ENTER  | 
I  ENTER  I 
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If  your  system  disk  already  has  a  Startup  file: 

First  rename  the  Startup  file  by  typing: 

rename    startup   oldstart  | ENTER  | 

Then  create  a  file  that  contains  the  new  command,  such  as: 

build    news  tart  |  EMTER  | 
montype    r  |  ENTER  | 
I  ENTER  I 


Now  combine  the  two  files  into  a  new  Startup  file: 

merge   oldatart    newstart    >    startup  [  ENTER  | 

Use  DEL  to  delete  oldstart,  newstart,  or  both,  or  leave  them  on 
your  disk  for  future  use. 

Using  Windows 

If  the  window  descriptors  <W,  Wl,  W2,  W3,  W4,  W5,  W6,  W7) 
and  the  graphics  interface  and  driver,  Grflnt  and  GrfDrv,  are  in 
memory,  OS-9  lets  you  set  up  windows  on  your  display  screen. 

Note:  Grflnt  and  the  window  descriptors  must  be  loaded  as 
part  of  the  boot  operation.  Your  System  Master  diskette  does 
this. 

Once  you  have  initialized  windows,  you  can  then  move  among 
them,  initiating  different  tasks  in  each.  You  can  even  have  differ- 
ent processes  showing  on  different  portions  of  your  display  screen 
at  the  same  time. 

Another  advantage  of  using  windows  is  that  you  can  choose  win- 
dows that  give  you  displays  of  40  or  80  columns  across  the  screen, 
rather  than  only  32.  However,  unless  you  have  a  monitor  con- 
nected to  your  computer,  rather  than  a  television,  you  might  be 
unable  to  read  the  screen. 

Establishing  a  Window 

You  can  establish  one  or  more  windows  after  booting  OS-9,  or  you 
can  include  the  window  creation  process  in  OS-9's  Startup  file. 
Startup  is  a  file  containing  commands  you  want  your  system  to 
execute  during  startup. 
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To  establish  a  window  from  the  OS-9  prompt,  type: 


iniz    w number  |  ENTER  | 
shell    i  =  /w  number*  |  ENTER  I 


In  this  example,  number  represents  the  window  number  to  ini- 
tialize. After  you  type  these  commands,  you  can  select  the  win- 
dow  by  pressing  1  clear  [.  To  return  to  the  original  screen,  press 
[  clear  |  again. 

The  default  values  for  the  window  descriptors  AVI  through  AV7 
are: 

Window  Text  size       Window's  physical  size 

device  name    in  columns     Starts  at:  Size: 


AVI 

40 

0,0 

27,11 

AV2 

40 

28,0 

12,11 

AV3 

40 

0,12 

40,12 

AV4 

80 

0,0 

60,11 

AV5 

80 

60,0 

19,11 

AV6 

80 

80,0 

80,12 

AV7 

80 

0,0 

80,24 

Note:  To  initialize  Windows  AV2  and  AV3,  you  must 
be  operating  from  Window  AVI.  To  create  Windows 
AV5  and  AV6,  you  must  be  operating  from  Window 
AV4. 

The  "Starts  at"  column,  indicates  the  position  on  the  screen  of  the 
top  left  comer  of  the  window.  On  the  screen  grid,  coordinates  0,0 
are  located  at  the  top  left  corner, 

The  "Size:"  column  indicates  the  number  of  characters  across  each 
window  and  the  number  of  character  lines  in  each  window. 

Therefore,  Window  1  displays  40  column  text,  begins  in  the  top 
left  corner  of  the  screen,  extends  right  for  27  characters  and  down 
for  11  lines.  Window  5  displays  80  column  text,  begins  at  the  top 
of  the  screen,  60  columns  from  the  left,  extends  19  columns  to  the 
right  and  11  lines  down. 

Note  that  the  coordinates  for  each  window  are  based  on  the  text 
size  of  the  screen.  Therefore,  Window  1  (based  on  40  column  text) 
ends  at  column  27,  while  Window  5  (based  on  80  column  text) 
begins  at  column  60. 
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Using  the  information  in  the  previous  chart,  you  can  now  estab- 
lish any,  or  all,  of  the  seven  windows. 

Note:  You  cannot  establish  all  of  the  windows  unless  your 
computer  has  512  kilobytes  of  memory. 

For  instance,  to  set  up  a  full  screen,  80-column  window,  type: 


shell    i  =  /w7&  I  ENTER  I 


After  a  short  pause,  the  screen  displays  a  message,  such  as: 

This  means  that  OS-9  has  opened  a  path  to  your  new  window  and 
started  a  shell  on  the  window  with  the  process  identification  of  04. 
To  move  to  the  window,  press  [  clear  |.  Your  32-column  screen  van- 
ishes and  you  are  now  in  Window  7.  You  can  type  commands  or 
run  programs  from  here  in  the  same  manner  as  before. 

To  set  up  three  windows  on  the  same  screen,  type  these  com- 
mands, then  use  [  clear  |  to  move  among  the  windows: 


iniz    w1     w2    w3  |  ENTER  | 
shell     i  =  /w1i  l  ENTER  I 


Shell     i»/w24  |  ENTER  | 
shell    l-/w3  4  (ENTER! 


If  you  want,  and  your  computer  has  enough  memory,  you  can  run 
different  processes  in  all  of  the  windows. 


Changing  Window  Colors 

Perhaps  you  don't  like  the  color  of  the  screen  in  one  or  more  of 
your  windows.  You  can  change  it  using  the  display  command.  The 
following  charts  show  you  all  of  the  colors  available  for  the  screen 
background,  text,  and  border. 
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Background  Code  = 

=  33 

Text  Code  =  32 

Border  Code  =  34 

Color  Codes 

Codes 

Color 

00  or  08 

White 

01  or  09 

Blue 

02  or  0A 

Black 

03  or  0B 

Green 

04  or  0C 

Red 

05  or  0D 

Yellow 

06  or  OE 

Magenta 

07  or  OF 

Cyan 

10  or  greater     Black 

To  change  a  color,  type  DISPLAY  lb,  followed  by  the  background, 
text,  border,  or  foreground  code  followed  by  a  color  code.  Then, 
press  |  ENTER  |. 

For  instance,  if  you  are  in  Window  7,  you  can  change  the  back- 
ground color  to  red,  by  typing: 


display    1b    33    04  |  ENTER  I 

Change  the  text  color  to  black  by  typing; 


display    1b    32    02  [  ENTER  | 

To  put  a  white  border  around  the  screen,  type: 


di5play    1b    34    0 0  [  ENTER  | 

You  can  also  type  all  the  codes  on  one  line,  like  this: 

display   1b    33   04    1b   32    00    1b    34    00  |  ENTER  I 

Pick  the  colors  you  want  for  each  window,  and  change  them  using 
DISPLAY. 


Eliminating  a  Window 

In  the  command  to  establish  windows  (shell  i  =  /vmumber&),  "i" 
tells  SHELL  that  the  process  being  created  is  immortal.  This 
means  that  you  can  only  terminate  it  from  the  window  in  which 
it  resides. 
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To  kill  a  window  in  which  you  have  established  a  shell,  press 
[  clear  1  until  the  window  you  want  appears  on  the  screen.  Type: 


=  x  I  EWER  | 

Now  press  I  clear  |  to  move  to  another  window  in  which  a  shell  is 
running,  Then  use  DEINIZ  to  deinitialize  that  window.  For 
instance,  if  the  window  you  want  to  eliminate  is  Window  1,  type: 


deiniz   w1  I  ENTER  I 


Using  Startup  To  Establish  A  Window 

If  you  intend  to  use  a  window  whenever  you  start  OS-9,  for 
instance  if  you  want  to  use  an  80  column  screen,  put  the  appro- 
priate commands  in  the  Startup  file.  This  file  must  be  located  in 
the  ROOT  directory  of  your  system  disk. 

If  your  system  diskette  already  has  a  Startup  file: 

First  rename  the  existing  Startup  file,  such  as: 


rename    startup    oldstart  |  ENTER  | 

Then  put  your  new  commands  into  a  temporary  file.  To  initialize 
window  Number  7  (80  columns,  full  screen)  with  white  text  on  a 
black  background,  type: 

build    tempstart 
inw    w7  I  ENTER  I 


shell     i-/w7&     ENTER 


display    1b    32    00    1b    33    02    1b    34    02    0c    >    /w7  |ENTER| 


ENTER 


Now  combine  your  new  commands  with  the  original  Startup  file 
by  typing: 


merge    oldstart    tempstart    >    startup  [  ENTER  ] 

You  can  remove  the  Tempstart  file  by  typing  del  tempstart 
I  enter  l,  or  you  can  leave  it  in  your  ROOT  directory  for  future  use. 
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If  Startup  does  not  already  exist: 

Create  it  by  typing: 


build    startup  [ENTER] 
iniz   w7  I  ENTER  I 


display    1b    32    00    1b   33    02    1b   34    02    0c    >    /w7  |  ENTER  | 
ahell     i-/w7*  I  ENTER  I 


ENTER 


Now,  after  you  boot  OS-9,  press  |  clear  |  to  operate  in  an  80- 
column,  black  and  white  screen. 


7-14 


Index 


adding  commands  7-7 

ALT  5-8 

anonymous  directory  names  4-6 

application  1-2 

diskette  1-2 

programs  1-2,  3-5 
arrow  keys  1-2,  5-8,  5-9 
ASCII  value  5-8 
auto-repeat,  keyboard  5-8 

backslash  character  5-9 
backup  3-5 

diskettes  3-3 

files  6-3 
BASIC09/CONFIG  diskette  3-5,  3-7 
bit,  high  order  5-8 
booting  OS-9  2-2 
brace  5-9 

bracket  character  5-9,  5-10 
BUILD  7-8,  7-13 

care  of  diskettes  3-1 
carriage  return  5-10 
changing 

directories  5-6 

the  system  diskette  5-7 
character 

ASCII  5-8 

backslash  5-9 

brace  5-9 

tilde  5-9 

underscore  5-9 

up  arrow  5-9 

valid  4-5 

vertical  bar  5-9 
clock  module  7-6 
CMDS  directory  4-1,5-5 
colors,  window  7-1 1,7-12 
command  1-1,  6-1 

accessing  5-4 

adding  7-7 

editing  5-1 

loading  6-5 

line,  1-1,  1-2,  5-1 

using  spaces  5-2 

mistakes  5-1 


modules,  listing  6-5 

option  5-2 

parameters  5-2 

process,  5-10 

typing  5-1 
communications  pak  1-3 
composite  monitor  7-8 
computer,  turning  off  2-3,  3-1 
CONFIG  7-1 

configuring  your  system  7-1 
contents  of  directories  6-1 
control  key  5-8 
CONTROL-C  5-9 
copies 

with  one  drive  3-5 

with  two  drives  3-7 
COPY  5-2,  5-4 
copying 

diskettes  3-3,  3-5 

files  6-3 
CTRL-BREAK  5-9 
CTRL-C1-1 
CTRL-H  5-1 
CTRL-X  5-1 

current  execution  directory  5-5 
cursor,  move  5-8 
customizing  your  system  7-1 

data  4-1 

directory,  changing  5-7 

files  4-1 

terminal  1-3 

types  4-1 

storing  4-1 
date  2-2 
DEINIZ7-13 
deleting 

lines  5-9 

directory  files  6-2 

files  6-4 

memory  modules  6-6 
descriptors,  window  7-10 
destination  diskette  3-6 
device  names  4-6,  7-3 
DIR  5-2 


Getting  Started  With  OS-9 


directory  4-1 

changing  5-6 

changing  the  data  5-7 

CMDS4-1 

contents  6-2 

creating  6-1 

current' execution  5-5 

deleting  6-2 

display  6-2 

finding  4-5 

multiple  4-4 

pathlist  4-5 

ROOT  4-1,  4-5 

SYS  4-2 

viewing  6-1 
directory  names  4-4 

anonymous  4-6 

displaying  6-2 
disk  drive  1  -4 

names  3-2, 
disk  name  3-3,  4-6 
diskette 

backup  3-5 

copying  3-3 

formatting  3-3,  3-4 

handling  3-1 

removing  5-7 

track  3-3 

BASIC09/CONFIG  3-5 

changing  the  system  5-7 

destination  3-6 

source  3-6 

system  7-1 

write  protect  3-2 
DISPLAY  7-12 
display 

directory  6-2 

directory  names  6-2 

file  5-2 

video  5-8 
drive  names  3-2 
DSAVE  6-5 
duplicate  diskette  3-6,  3-7 

editing  commands  5-1 
end-of-file  5-9 
entering  commands  5-1 
error  message  1-5,  2-4 
ESCAPE  function  5-9 
examples  of  filenames  4-4 


execution  directory  5-5 
exit  OS-9  2-3 
extended  DIR  5-3 

files  4-1 

copying  6-3 

deleting  6-4 

display  5-2 

finding  4-5 

names  4-4 

pathlist  4-5 

renaming  6-4 

Startup  7-8 

viewing  6-5 
filename 

examples  4-4 

legal  characters  4-4 

finding  4-5 

directories  4-5 
formatting 

diskette  3-3,  3-4 

with  two  drives  3-4 

graphics 

characters  5-8 
interface  7-9 

halt  video  output  5-10 
handling  diskettes  3-1 
hard  disk  name  3-2 
hardware  1-3 
high  order  bit  5-8 

initialize  diskette  3-3,  3-4 
INIZ7-10 

interface,  graphics  7-9 
international  characters  5-8 

key,  control  5-8 
keyboard 

mouse  5-9 

auto -repeat  5-8 
keys,  arrow  5-8,  5-9 
kill  a  window  7-13 

languages  1-2 

last  line,  redisplay  5-10 

left  brace  5-9 

left  bracket  5-9 

legal  characters,  filenames  4-4 


Index 


length,  command  line  5-1 
line 

command  5-1 

delete  5-9 

redisplay  5-10 
listing  command  modules  6-5 
loading  commands  6-5 
lowercase  letters  2-4,  5-1,  5-8 

memory  modules  6-5 

deleting  6-6 
menus  1-2 
messages,  error  2-4 
mistakes,  command  5-1 
modem  1-3, 1-4 
modifier  5-1 
module,  clock  7-6 
modules 

in  memory  6-5 

window  7-6 
monitor  5-8,  7-8 

monochrome  7-8 
mouse,  keyboard  5-9 
move  cursor  5-8 
multi-pak  interface  1-3,  2-1 
multi-tasking  1-4 
multi-user  1  -4 
multiple  directories  4-4 

names 

anonymous  4-6 
device  4-6 
directory  4-4 
disk  drive  3-2 
file  4-4 
hard  disk  3-2 
of  devices  7-3 

one  drive  copies  3-5 
operating  system  1-1 
option,  command  5-2 
OS-9,  starting  2-1 
output,  halt  video  5-10 

parameter  5-1 

command  5-2 
pathlist  4-5,  4-6 

periods,  anonymous  names  4-6 
peripherals  1-3 
process  command  5-10 


program  4-1 

application  3-5 

execution,  stopping  5-8 

files  4-1 

name  5-1 
protect  diskettes  3-2 

quit  OS-9  2-3 

rebooting  OS-9  2-3 
redisplay 

current  line  5-10 

last  line  5-10 
removing 

diskettes  5-7 

windows  7-1 2 
renaming  files  6-4 
reset  button  2-3 
RGB  monitor  7-8 
right  brace  5-9 
ROOT  directory  4-1,  4-2,  4-5 
route  to  files  4-5 
RS-232  1-3,  2-1 

scratched  3-6,  3-7 
screen,  VDG  5-8 
sector  3-4 
select  window  5-9 
serial  port  1  -3 
SHELL  7-11 
shift  lock  5-9 
size  of  windows  7-10 
slash 

in  device  names  4-6 

in  pathlist  4-5,  5-7 
SN  error  2-2 
source  diskette  3-6 
spaces  in  a  command  line  5-2 
special  keys  5-8 
starting 

OS-9  2-1 

your  computer  2-1 
Startup  7-8 

file  7-13 
stopping  program  execution  5-8 
storing 

data  4-1 

diskettes  3-1 
subdirectory  4-2 
substitute  names  4-6 


Getting  Started  With  OS-9 


syntax  error  2-2 
SYS  directory  4-2 
system 

customizing  7-1 

devices  7-3 

diskette  7-1 

name  1-3 

TERM  5-8 

TERM_VDG  7-5 

TERM_WIN  7-5 

terminal  1-3 

text  file  5-2 

tilde  5-9 

time  2-2 

track  3-3,  3-4 

turning  off  your  computer  3-1 

two  drive 

copies  3-7 

formatting  3-4 
types 

of  data  4-1 

of  monitors  7-8 

underscore  character  5-9 


up  arrow  5-9 
uppercase  2-4,  5-1,  5-8 

valid  character  4-4,  4-5 

VDG  screen  5-8 

vertical  bar  5-9 

video 

display  5-8 
output,  halt  5-10 
window,  select  5-9 

viewing  files  6-5 

window  1-4,  7-9 

40-coiumn  7-5 
80-column  7-5 
colors  7-11,  7-12 
descriptors  7-10 
eliminating  7-12 
establishing  7-9 
modules  7-6 
names  4-6 
path  7-1 1 
size  7-10 
establish  7-13 

write  protect  3-2,  3-3 


Getting  Started  With  OS-9 


Anonymous  Directory  Names 

lb  save  time,  or  if  you  do  not  know  a  full  pathlist,  you  can  refer 
to  the  current  directory,  or  to  a  higher-level  directory,  using  an 
anonymous  name,  or  name  substitute,  as  follows: 

•  One  period  (.)  refers  to  the  current  directory 

•  Two  periods  (..)  refer  to  the  parent  of  the  current  direc- 
tory (the  next  highest-level  directory). 

•  Three  periods  (...)  refer  to  the  directory  two  levels  up,  and 
soon. 

Yaa  can  use  an  anonymous  directory  name  in  place  of  a  pathlist 
or  as  the  first  name  in  a  pathlist.  Some  examples  are: 

d  i  r    . .  |  enter  1  lists  names  in  the  current  data  direc- 

tory's parent  directory. 

del  .  ./temp  | enter l deletes  the  file  called  Temp  from  the 
current  data  directory's  parent 
directory. 

Anonymous  names  can  refer  to  either  execution  or  data  directo- 
ries, depending  on  the  context  in  which  you  use  them. 

About  Device  Names 

In  the  same  manner  that  OS-9  has  names  for  its  commands,  it 
also  has  names  for  its  devices.  These  names  are  abbreviations  of 
actual  device  names.  For  instance,  instead  of  typing  Disk  Drive  0 
to  refer  to  your  first  disk  drive,  you  only  need  to  type  /D0.  To 
refer  to  your  printer,  type  /P.  OS-9  windows  are  named  AV 
through  /W7. 

All  of  OS-9's  device  names  are  preceded  by  a  slash — this  is  how 
OS-9  can  tell  you  are  referring  to  a  device  rather  than  a  direc- 
tory or  file.  When  you  purchase  your  System  Master  diskette,  OS- 
9  is  configured  to  recognize  two  disk  drives,  a  printer,  and  one 
terminal  port.  For  information  on  how  to  configure  your  system  to 
recognize  other  devices,  see  Chapter  7. 
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Chapter  1 

Introduction 


Getting  Started  With  OS-9  contains  the  information  you  must 
know  to  use  the  system.  However,  the  handbook  reveals  only  a 
small  part  of  OS-9's  capabilities,  lb  learn  about  all  of  its  fea- 
tures, you  need  to  know  more  about  how  OS-9  works.  This  intro- 
duction provides  such  basic  background  information. 

The  Kernel 

At  the  center  of  the  OS-9  system  is  a  module  (program)  called  a 
kernel.  (See  the  following  illustration.)  The  kernel  provides  basic 
system  services,  such  as  multitasking  and  memory  management. 
It  links  other  system  modules  and  serves  as  the  system  adminis- 
trator, supervisor,  and  resource  manager. 
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Figure  1 

Term  is  your  keyboard  and  video. 

Tl  and  T2  are  additional  terminals. 

P  is  a  printer. 

Ml,  M2,  and  M3  are  modems. 
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The  Input/Output  Manager 

Although  the  kernel  manages  OS-9,  it  does  not  directly  process 
the  input  and  output  of  data  among  the  other  modules  and  your 
computer  hardware  (printers,  disk  drives,  terminals,  and  so  on). 
Instead  the  kernel  passes  this  responsibility  to  the  input/output 
manager,  IOMAN. 

IOMAN  has  three  submanagers:  a  character  file  manager,  a  pipe 
file  manager,  and  a  disk  file  manager.  The  responsibilities  of 
these  managers  are  as  follows: 

The  Character  Handles  the  transfer  of  data  between  OS-9 
File  Manager  and  character  devices  (devices  that  operate 

on  a  character-by-character  basis,  such  as 
terminals,  printers,  or  modems).  The 
sequential  character  file  manager  (SCF)  can 
handle  any  number  or  type  of  such  devices. 

The  Pipe  File  Handles  communication  between  processes 

Manager  or  tasks.  Pipes  let  you  use  the  output  of  one 

process  as  the  input  of  another  process. 

The  Disk  File  This  Random  Block  File  Manager  (RBF) 

Manager  handles  the  transfer  of  data  to  and  from 

block-oriented,  random  access  devices,  such 

as  a  disk  drive  system. 

Device  Drivers 

CC3IO,  PIPER,  and  CC3DISK  are  device  drivers.  These  files  con- 
tain code  that  transforms  standard  data  into  a  form  acceptable 
to  a  particular  device,  whether  it  is  a  terminal,  printer,  modem, 
disk  drive,  any  other  device,  or  another  file,  PIPES  transfers 
data  between  processes. 

Device  Descriptors 

Term,  Tl,  P,  Ml,  DO,  and  so  on,  are  device  descriptors.  These 
files  describe  the  devices  connected  to  the  system.  They  contain 
device  initialization  data  as  well  as  code  that  directs  OS-9  to  the 
physical  addresses  of  the  ports  to  which  devices  are  connected. 
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The  Shell 

The  kernel,  in  conjunction  with  IOMAN  and  its  associated  man- 
agers and  modules,  make  up  the  OS-9  operating  system.  These 
modules  handle  all  of  the  system's  functions.  However,  OS-9 
needs  directions  before  it  can  accomplish  useful  tasks. 

Directions  to  the  system  have  two  sources:  commands  and  appli- 
cations or  computer  language  programs. 

Before  commands  are  useful  to  the  kernel,  the  shell  must  inter- 
pret them.  It  analyzes  commands  and  converts  them  into  code 
that  the  kernel  can  understand. 

Some  application  programs  and  computer  languages  also  use  the 
shell's  functions.  Others  can  access  the  kernel  directly  and  do  not 
need  to  go  through  the  shell. 

Going  On 

Chapters  2  through  5  contain  detailed  information  on  the  opera- 
tion of  the  OS-9  system  illustrated  in  Figure  1.  These  chapters 
more  fully  describe  the  composition  of  files  and  directories.  They 
tell  about  advanced  features  of  commands  and  of  the  shell  and 
contain  information  on  multiprogramming  and  memory 
management. 

Chapter  6  contains  descriptions  of  the  OS-9  commands.  Chapter 
7  tells  you  how  to  use  OS-9's  Macro  Text  Editor. 
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Input  and  output  refer  to  the  data  your  computer  system 
receives  and  the  data  that  it  sends,  OS-9  can  receive  (input) 
data  from  a  keyboard,  disk  files,  modems,  and  other  terminals.  It 
can  send  (output)  data  to  all  of  these  devices — except  the  key- 
board— and  to  a  video  display. 

OS-9  receives  and  sends  data  in  the  same  format,  regardless  of 
whether  the  destination  is  a  file  or  a  device.  It  overcomes  the  dif- 
ferences in  the  devices  by  defining  a  standard  for  them  and  using 
device  drivers  to  make  each  device  conform  to  the  standard.  The 
result;  a  much  simpler  and  more  versatile  input/output  system. 

Input/Output  Paths 

The  base  of  OS-9's  unified  I/O  system  is  an  organization  of 
paths.  Input/output  paths  are,  in  effect,  software  links  between 
files.  (Remember,  OS-9  thinks  of  all  devices  as  files.) 

Individual  device  drivers  process  data  so  that  it  conforms  to  the 
hardware  requirements  of  the  device  involved.  Data  transfer  is  in 
streams  of  8-bit  bytes  that  can  be  either  bidirectional  (read/ 
write)  or  unidirectional  (read  only  or  write  only),  depending  on 
the  device,  how  you  establish  the  path,  or  both.  A  byte  is  a  unit 
of  computer  data.  (A  byte  may  contain  the  code  for  one  alphabet 
character.)  A  bit  is  a  binary  digit  and  has  a  value  of  either  0  or 
1. 

OS-9  does  not  require  the  data  it  manages  to  have  any  special 
format  or  meaning.  The  meaning  of  the  data  is  determined  by 
the  programs  that  use  it. 

Some  of  the  advantages  of  such  a  unified  I/O  system  are: 

•  Programs  operate  correctly  regardless  of  the  I/O  devices 
selected. 

•  Programs  are  highly  portable  from  one  computer  to 
another,  even  when  the  computers  have  different  types  of 
I/O  devices. 

•  "¥bu  can  redirect  I/O  to  alternate  files  or  devices  when 
you  run  a  program,  without  having  to  alter  the  program. 
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•  You  can  easily  create  and  install  new  or  special  device 
driver  routines. 

Disk  Directories 

A  directory  is  a  storage  place  for  other  directories  and  files.  It 
contains  the  information  about  the  directories  and  files  assigned 
to  it  so  that  OS-9  can  easily  find  and  access  the  data  they 
contain. 

Each  disk  has  its  own  directory  system.  For  example,  a  typical 
system  diskette,  diagrammed  partially  and  simply,  might  look 
like  this: 

DO  (Drive  /DO) 
V 


/DO  ROOT  Directory 


] 


SYS  Startup  CMOS 

V 

Errmsg 


copy         list  dir  del        format 


The  ROOT  directory  of  /DO— the  ROOT  from  which  the  rest  of 
the  disk's  file  system  grows — contains  a  file  called  Startup  and 
two  directories,  SYS  and  CMDS. 

SYS  and  CMDS,  in  turn,  contain  files:  SYS  contains  Errmsg, 
and  CMDS  contains  Copy,  List,  Dir,  Del,  and  Format.  All  these 
files  and  directories,  and  many  more,  come  built  into  the  OS-9 
system. 

OS-9  organizes  each  directory  area  into  32-byte  records.  The 
first  29  bytes  contain  filename  characters.  The  first  byte  of  the 
name  has  its  sign  bit  (the  leftmost  or  most  significant  bit)  set. 
When  you  delete  a  file,  it  is  not  immediately  destroyed.  Rather, 
the  deletion  process  sets  the  first  character  position  of  the  record 
to  zero,  and  OS-9  no  longer  recognizes  the  record.  Although  the 
file  contents  still  exist,  they  are  no  longer  accessible  to  you  or 
OS-9.  Subsequent  file  creations  overwrite  deleted  records. 
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The  last  three  bytes  of  a  record  make  up  a  24-bit  binary  number 
that  is  the  logical  sector  number  pointing  to  the  file  descriptor 
record.  Logical  sectors  are  numbered  with  reference  to  the 
sequence  of  their  use,  rather  than  their  physical  location  on  a 
disk.  See  "Disk  Files"  for  more  information  on  disk  organization. 

"You  create  directories  using  the  MAKDIR  command  and  can 
identify  them  by  the  D  (directory)  attribute.  (See  "Examining 
and  Changing  File  Attributes".)  MAKDIR  initializes  each  direc- 
tory with  two  entries  having  the  names  "."  and  "..".  These 
entries  contain  the  logical  sector  numbers  of  the  directory  and 
its  parent  directory,  respectively. 

You  cannot  use  the  COPY  and  LIST  commands  (as  described  in 
Getting  Started  With  OS-9)  with  directories.  Instead,  use  DSAVE 
and  DIR. 

You  cannot  delete  directories  directly.  You  must  first  empty  a 
directory  of  files,  convert  it  into  a  standard  file,  and  then  delete 
it.  However,  the  DELDIR  command  performs  all  these  functions 
automatically. 

Subdirectories 

A  subdirectory  is  a  directory  residing  in  another  directory. 
Actually,  all  directories  you  create  are  subdirectories,  since  all 
directories  branch  from  the  ROOT  directory.  However,  because 
the  system  automatically  creates  the  ROOT  directory  when  you 
format  a  disk,  this  manual  does  not  consider  directories  residing 
in  the  ROOT  directory  to  be  subdirectories. 

Subdirectories  can  contain  files  and  other  subdirectories.  In 
effect,  OS-9  catalogues  files  and  directories  in  much  the  same 
way  that  you  might  put  files  pertaining  to  a  particular  subject 
in  a  file  cabinet  drawer.  With  OS-9,  you  can  have  as  many  direc- 
tory levels  as  your  disk  storage  space  permits. 

Disk  Files 

A  disk  file  is  a  logical  block  of  data.  (Logical  means  that 
although  the  data  might  not  actually  exist  in  a  contiguous  block, 
OS-9  treats  it  as  though  it  does.)  A  file  can  contain  a  program, 
text,  a  command,  a  computer  language,  or  any  other  form  of 
code.  Every  time  you  ask  OS-9  to  store  data  on  a  disk,  you  must 
specify  a  filename  for  that  block  of  data.  Both  you  and  the  sys- 
tem must  then  use  the  filename  to  access  the  data. 


2-3 


OS-9  Commands  Reference 


The  system  stores  all  files  as  an  ordered  sequence  of  8-bit  bytes. 
The  file  can  be  any  size  from  0  bytes  to  the  maximum  capacity 
of  the  storage  device  and  can  be  expanded  or  shortened  as 
desired. 

When  OS-9  creates  or  opens  a  file,  it  establishes  a  file  pointer  for 
it.  OS-9  addresses  bytes  within  the  file  in  the  same  manner  it 
addresses  memory,  and  the  file  pointer  holds  the  address  of  the 
next  byte  to  write  or  read.  OS-9's  read  and  write  functions 
always  update  the  pointer  as  the  system  transfers  data. 

This  pointer  function  lets  assembly-language  programmers  and 
high-level  language  programmers  reposition  the  file  pointer.  To 
expand  a  file,  write  past  the  previous  end  of  the  file.  Reading  up 
to  the  last  byte  of  a  file  causes  the  next  read  request  to  return 
an  end-of-file  status. 

OS-9's  file  system  also  uses  a  universal  organization  for  all  I/O 
devices.  This  feature  means  that  application  programs  can  treat 
each  hardware  device  similarly.  The  following  section  gives  basic 
information  about  the  physical  file  structure  used  by  OS-9.  (For 
more  information,  see  the  OS-9  Level  Two  Technical  Reference 
manual.) 

Sectors 

The  data  contained  in  a  file  is  stored  in  one  or  more  sectors  (disk 
storage  units).  These  file  sectors  have  both  a  logical  and  a  physi- 
cal arrangement.  The  logical  arrangement  numbers  the  sectors 
in  sequence.  The  physical  arrangement  can  be  in  any  order 
based  on  the  actual  location  of  a  sector  on  a  disk's  surface.  For 
instance,  Logical  Sector  1  might  be  located  at  Physical  Sector 
10,  and  Logical  Sector  2  might  be  located  at  Physical  Sector  19. 

Each  sector  contains  256  data  bytes.  The  first  sector  of  every  file 
(Logical  Sector  Number  0  or  LSN  0)  is  called  the  file  descriptor. 
It  contains  the  logical  and  physical  description  of  the  file.  The 
disk  driver  module  links  sector  numbers  to  physical  track/sector 
numbers  on  a  disk. 

A  sector  is  the  smallest  physical  unit  of  a  file  that  OS-9  can 
allocate  for  storage.  On  the  Color  Computer,  a  sector  is  also  the 
smallest  file  unit.  (To  increase  efficiency  on  some  larger-capacity 
disk  systems,  OS-9  uses  uniform-sized  groups  of  sectors,  called 
clusters,  as  the  smallest  allocatable  unit.  A  cluster  is  always  an 
integral  power  of  two — 2,  4,  8,  and  so  on.) 
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OS-9  uses  one  or  more  sectors  of  each  disk  as  a  bitmap  (usually 
starting  at  LSN  1)  in  which  each  data  bit  corresponds  to  one 
cluster  on  the  disk.  The  system  sets  and  clears  bits  to  indicate 
which  clusters  it  is  using,  which  clusters  are  defective,  and 
which  clusters  are  free  for  allocation.  The  Color  Computer 
default  floppy  disk  system  uses  this  format: 

•  Double-density  recording  on  one  side 

•  35  tracks  per  diskette 

•  18  sectors  per  track 

•  One  sector  per  cluster 

Each  OS-9  file  has  a  directory  entry  that  includes  the  filename 
and  the  logical  sector  number  of  the  file's  file  descriptor  sector. 
The  file  descriptor  sector  contains  a  complete  description  of  its 
file,  including: 

•  Attributes 

•  Owner 

•  Date  and  time  created 

•  Size 

•  Segment  list  (description  of  data  sector  blocks) 

Unless  the  file  size  is  0,  the  file  uses  one  or  more  sectors/clusters 
to  store  data.  The  system  groups  data  sectors  into  one  or  more 
adjacent  blocks  called  segments. 

Text  Files 

Text  files  contain  variable-length  lines  of  ASCII  characters.  A 
carriage  return  (ASCII  code  0D  hexadecimal  or  13  decimal)  ter- 
minates each  line.  Text  files  contain  such  data  as  program 
source  code,  procedure  files,  messages,  and  documentation. 

Programs  usually  read  text  files  sequentially.  Almost  all  high- 
level  languages  (such  as  BASIC09)  support  text  files. 

Use  LIST  to  examine  the  content  of  text  files. 
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Random-Access  Data  Files 

Random-access  files  consist  of  sequences  of  records,  with  each 
record  the  same  length.  A  program  can  find  any  record's  begin- 
ning address  by  multiplying  the  record  number  by  the  number  of 
bytes  used  for  each  record.  This  feature  allows  direct  access  of 
any  record. 

Usually,  high-level  languages  let  you  subdivide  records  into 
fields.  Each  field  can  have  a  fixed  length  and  use.  For  example, 
the  first  field  of  a  record  can  be  25  text  characters  in  length,  the 
next  field  can  be  two  bytes  in  length  and  used  to  hold  16-bit 
binary  numbers,  and  so  on. 

OS-9  does  not  directly  process  records.  It  only  provides  the  basic 
file  functions  used  by  high-level  languages  to  create  and  handle 
random-access  files. 

Programmers  use  high-level  languages  like  BASIC09,  Pascal, 
and  C  to  create  random-access  data  files.  For  instance,  in 
BASIC09  and  Pascal,  GET,  PUT,  and  SEEK  functions  operate 
on  random-access  files. 

Procedure  Files 

Procedure  files  are  disk  files  that  contain  commands.  You  can 
use  them  to  execute  a  series  of  commands  by  typing  and  enter- 
ing a  single  command  name. 

Your  System  Master  diskette  contains  one  procedure  file  named 
Startup.  You  can  create  your  own  procedure  files  using  the 
BUILD  command,  copying  input  from  the  keyboard  to  a  file,  or 
by  using  a  text  editor  program.  For  instance,  suppose  you  have 
three  disk  drives,  /DO,  /Dl,  and  /HO.  You  could  create  three  very 
simple  procedures  to  allow  you  to  look  at  the  directories  of  these 
disks  by  typing  and  entering  a  simple  two-character  command. 

To  create  a  procedure  file  to  look  at  the  directory  of /Dl,  type: 
build  pi  | enter | 

display    0  C  |  ENTER  | 
dir     /d1  j  ENTER  | 
display   0A  |  ENTER  | 
I  ENTER  | 
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The  first  line  creates  a  file  named  PI  (print  directory  for  Drive 
/Dl).  When  you  press  [enter],  a  question  mark  appears  on  the 
screen  telling  you  that  OS-9  is  waiting  for  input.  Type  the  rest 
of  the  lines.  Finally,  press  |  enter  |  at  the  beginning  of  a  line  to 
tell  OS-9  that  the  input  is  complete.  OS-9  closes  the  file. 

Now,  to  see  the  contents  of  Drive  /Dl,  type  p1  I  enter  |.  The  com- 
mand display  0C  clears  the  video  screen.  The  command 
display  0A  causes  the  cursor  to  drop  down  one  line  on  the 
screen. 

Use  your  imagination.  Almost  anything  you  can  do  from  the  key- 
board, you  can  do  with  a  procedure  file.  However,  remember  that 
OS-9  looks  only  in  the  current  data  directory  for  a  procedure 
file,  unless  you  provide  a  full  pathlist  to  the  procedure.  Also, 
OS-9  must  be  able  to  find  any  command  in  the  current  execution 
directory  that  is  part  of  a  procedure  file.  If  the  current  execution 
directory  does  not  contain  the  commands  you  need,  change  it, 
either  from  the  keyboard  or  as  part  of  your  procedure  file. 

Executable  Program  Module  Files 

OS-9  program  modules  are  executable  program  code,  generated 
by  an  assembler  or  compiled  by  a  high-level  language.  A  file  can 
contain  one  or  more  program  modules. 

Each  module  has  a  standard  format  that  includes  the  object  code 
(the  executable  portion  of  the  module),  a  module  header  that 
describes  the  type  and  size  of  the  module,  and  a  CRC  (Cyclic 
Redundancy  Checksum)  value.  The  system  stores  program  mod- 
ules in  files  in  the  same  structure  in  which  they  load  into  mem- 
ory. Because  OS-9  programs  are  position-independent,  they  do 
not  require  specific  memory  addresses  for  loading. 

Ebr  OS-9  to  load  program  module(s)  from  a  file,  the  file  execute 
attribute  must  be  set,  and  each  module  must  have  a  valid  mod- 
ule header  and  CRC  value.  If  you  or  the  system  alters  a  program 
module  in  any  way  (either  as  a  file  or  in  memory),  its  CRC 
check  value  becomes  incorrect,  and  OS-9  cannot  load  the  module, 

If  a  file  contains  two  or  more  modules,  OS-9  treats  them  as  a 
group  and  assigns  contiguous  memory  locations  for  them. 
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Using  LIST  on  program  files  or  any  other  files  that  contain 
binary  data,  causes  a  jumbled  display  of  random  characters  and 
an  error  message. 

Miscellaneous  File  Use 

OS-9's  basic  file  functions  are  so  versatile  that  you  can  devise 
almost  unlimited  numbers  of  special-purpose  file  formats  for 
particular  applications  that  require  formats  not  discussed  here 
(text,  random-access,  and  so  on). 

The  File  Security  System 

Each  file  and  directory  has  properties  called  ownership  and  attri- 
butes that  determine  who  can  access  the  file  and  how  they  can 
use  it. 

OS-9  automatically  stores  the  user  number  associated  with  the 
creation  of  a  file.  The  system  considers  the  owner  of  the  number 
to  be  the  owner  of  the  file. 

Security  functions  are  based  on  access  attributes.  There  are 
eight  attributes,  each  of  which  can  be  turned  off  or  on  indepen- 
dently. When  the  D  (directory)  attribute  is  on  for  a  file,  that  file 
is  a  directory.  (Only  MAKDLR  can  set  the  D  attribute  for  a  file.) 
When  the  S  (shareable)  attribute  is  on,  only  one  program  or  user 
can  access  the  file  at  a  time. 
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The  other  six  attributes  control  whether  the  file  can  be  read 
from,  written  to,  or  executed  by  either  the  owner  or  the  public 
(all  other  users.)  When  on,  these  six  attributes  function  as 
follows: 


Owner  read 
permission 

Owner  write 
permission 


Owner  execute 
permission 


The  owner  can  read  from  the  file.  Use  this 
permission  to  prevent  binary  files  from 
being  used  as  text  files. 

The  owner  can  write  to  the  file  or  delete  it. 
Use  this  permission  to  protect  important 
files  from  accidental  deletion  or 
modification. 

The  owner  can  load  the  file  into  memory 
and  execute  it.  To  be  loaded,  the  file  must 
contain  one  or  more  valid  OS-9  memory 
modules. 

Anyone  can  read  and  copy  the  file. 


Anyone  can  write  to  or  delete  the  file. 


Anyone  can  execute  the  file. 


Public  read 

permission 

Public  write 
permission 

Public  execute 
permission 

For  example,  if  a  file  has  all  permissions  on  except  write  permit 
to  public  and  read  permit  to  public,  the  owner  has  unrestricted 
access  to  the  file.  Other  users  can  execute  it  but  cannot  read, 
copy,  delete,  or  alter  it. 

Examining  and  Changing  File  Attributes 

You  can  use  the  DIR  command,  with  the  E  (entire)  option,  to 
examine  the  security  permissions  of  all  files  in  a  particular 
directory.  An  example  of  output  using  DIR.  E  on  the  current  data 
directory  is: 

Directory   of    .    10:20:44 

Owner  Last  modified  Attributes  Sector  Bytecount  Name 


86/07/31  1436  r-wr 

86/07/31  1437  d-ewrewr 

86/07/31  1442  d-ewrewr 

86/07/31  1409  wr 


A 

6SG7  0S9Boot 

71 

568  CMDS 

IBS 

80  SYS 

IBd 

55  startup 
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The  Attributes  column  shows  which  attributes  are  on  by  listing 
one  or  more  of  the  following  codes. 


w 


w 


->  owner  read 


-=>  owner  write 

-5>  owner  execute 

>  public  read 

— >  public  write . 

public  execute 

1 — >  not  shareable 

1 — >  directory 
For  example,  the  first  file  shows: 
r-wr 

This  means  that  (1)  The  file  is  not  a  directory.  (2)  It  is  share- 
able. (3)  The  public  cannot  execute  it  or  (4)  write  to  it,  but  can 
(5)  read  it.  (6)  The  owner  cannot  execute  the  file,  but  can  (7) 
write  to  it,  and  (8)  can  read  it. 

To  examine  the  attributes  of  a  particular  file,  use  ATTR.  Typing 
ATTR  followed  by  a  filename  shows  you  the  file's  current  attri- 
butes, for  example: 


attr    f  ile2  I  ENTER  I 


A  possible  screen  display  is: 


wr-wr 


To  change  a  file's  attributes  use  ATTR  and  a  filename,  followed 
by  a  list  of  one  or  more  attribute  abbreviations.  However,  you 
must  own  a  file  before  you  can  change  its  attributes. 
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The  following  command  enables  public  write  and  public  read  per- 
missions and  removes  the  execute  permission  for  both  the  owner 
and  the  public: 


attr    f  ile2    pw    pr    -e    -pe  [ENTER] 

Note:  In  order  to  protect  data  stored  in  directories,  the  D 
attribute  behaves  somewhat  differently  from  the  other  attri- 
butes. Yon  cannot  use  ATTR  to  turn  on  the  D  attribute — 
only  MAKDIR  can  do  that — and  you  can  use  ATTR  to  turn 
off  D  only  if  the  directory  is  empty. 

Record  Lockout 

When  two  or  more  processes  use  the  same  file  simultaneously, 
they  might  attempt  to  update  the  file  at  the  same  time,  causing 
unpredictable  results.  When  you  open  a  file  in  the  update  mode, 
OS-9  eliminates  the  problem  of  simultaneous  use  by  locking  the 
sections  of  the  file.  The  lock  covers  any  disk  sectors  containing 
the  bytes  last  read  by  each  process  accessing  the  file.  If  one  pro- 
cess attempts  to  access  a  locked  portion  of  a  file,  OS-9  puts  the 
process  to  sleep  until  the  locked  area  is  free. 

OS-9  moves  the  lock  and  frees  the  area  when  it  reads  from  or 
writes  to  another  area.  The  system  removes  a  lock  on  a  file  when 
the  process  associated  with  the  lock  closes  its  path  to  the  file.  A 
process  can  have  only  one  lock  on  a  file,  but  it  can  have  locks  on 
more  than  one  file. 

Y>u  can  lock  an  entire  file  by  activating  its  single  user  bit.  (See 
the  earlier  section  "Examining  and  Changing  File  Attributes.") 
When  the  single  user  bit  is  on,  only  one  process  can  open  a  path 
to  the  file  at  a  time.  Attempts  by  other  processes  to  access  the 
file  result  in  an  error. 
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Device  Names 

Each  physical  I/O  device  supported  by  OS-9  has  a  unique  name. 
The  following  list  describes  the  device  names  supported  by  the 
system.  Your  system  diskette  already  defines  several  of  these 
devices.  You  can  define  others  using  CONFIG. 

D0-35S         Floppy  Disk  Drive  /DO,  single  sided,  35 

cylinders. 
D1_35S         Floppy  Disk  Drive  /Dl,  single  sided,  35 

cylinders. 
D2_35S         Floppy  Disk  Drive  /D2,  single  sided,  35 

cylinders. 
D3_35S         Floppy  Disk  Drive  /D3,  single  sided,  35 

cylinders. 
DDD0-35S  Default  Disk  Drive  /DO,  single  sided,  35 

cylinders. 
D0_40D        Floppy  Disk  Drive  /DO,  double  sided,  40 

cylinders. 
D1_40D        Floppy  Disk  Drive  /Dl,  double  sided,  40 

cylinders. 
D2_40D        Floppy  Disk  Drive  /D2,  double  sided,  40 

cylinders. 
D3_40D        Floppy  Disk  Drive  /D3,  double  sided,  40 

cylinders. 
DDD0_40D  Default  Disk  Drive  /DO,  double  sided,  40 

cylinders. 
D1_80D        Floppy  Disk  Drive  /Dl,  double  sided,  80 

cylinders. 
D2_80D        Floppy  Disk  Drive  /D2,  double  sided,  80 

cylinders. 
P  a  printer  using  the  RS-232  serial  port 

TERM  your  computer  keyboard  and  video  display 

Tl  a  terminal  port  using  the  standard  RS-232 

port 
T2  a  terminal  using  the  optional  RS-232 

communications  pak 
T3  a  terminal  using  the  optional  RS-232 

communications  pak 
Ml  a  modem  using  an  optional  300  baud  modem 

pak 
M2  a  modem  using  an  optional  300  baud  modem 

pak 
W  a  generic  window  descriptor 

Wl  window  device  Number  1 
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W2  window  device  Number  2 

W3  window  device  Number  3 

W4  window  device  Number  4 

W5  window  device  Number  5 

W6  window  device  Number  6 

W7  window  device  Number  7 

Although  OS-9  and  your  computer  can  access  all  these  devices, 
your  original  diskette  does  not  configure  it  to  do  so.  For  informa- 
tion on  configuring  your  system,  see  Chapter  7  of  Getting 
Started  With  OS-9. 

Because  device  names  are  at  the  root  of  the  file  system,  you  can 
use  them  only  as  the  first  part  of  a  pathlist.  Always  precede  the 
name  of  a  device  with  a  slash. 

When  you  refer  to  a  non-disk  device,  for  example  a  terminal  or 
printer,  use  only  the  device  name.  /P,  for  instance,  is  the  full 
allowable  pathlist  for  a  printer. 

Note:  An  I/O  device  name  is  actually  the  name  of  an  OS-9 
device  descriptor  that  you  precede  with  a  slash  {/).  OS-9 
automatically  loads  device  descriptors  during  the  OS-9  boot 
sequence.  "Vbu  can  add  or  delete  other  device  descriptors 
while  the  system  is  running  or  add  device  descriptors  to  the 
bootfile  using  CONFIG. 
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This  chapter  discusses  the  advanced  capabilities  of  the  shell.  In 
addition  to  basic  command  line  processing,  the  shell  facilitates: 

•  Input/output  redirection,  including  filters 

•  Memory  allocation 

•  Multitasking  (concurrent  execution) 

•  Procedure  file  execution 

•  Built-in  commands 

'You  can  use  these  advanced  capabilities  in  many  combinations. 
Following  are  several  examples.  Study  the  basic  rules,  use  your 
imagination,  and  explore. 

More  About  Command  Line  Processing 

The  shell  is  a  program  that  reads  and  processes  command  lines, 
one  at  a  time,  from  the  computer's  input  device  (usually  your 
keyboard).  It  parses  (scans)  each  line  to  identify  and  process  any 
of  the  following  parts  that  might  be  present: 

•  A  program,  procedure  file,  or  built-in  command 

•  Parameters  to  be  passed  to  the  program 

•  Execution  modifiers  to  be  processed  by  the  shell 

For  some  commands,  only  the  keyword  (the  program,  procedure 
file,  or  command  name)  must  be  present.  Other  commands  have 
required  or  optional  parameters.  As  well,  a  command  line  can 
include  modifiers  that  influence  the  operation  of  the  command. 
OS-9  features  that  affect  command  execution  are: 

Execution  Let  you  increase  the  amount  of  random  access 
Modifiers  memory  (RAM)  available  for  a  command.  Also 

lets  you  redirect  input  to  a  process,  output  from 

a  process,  or  both. 

Command  Let  you  enter  more  than  one  command  on  a  line, 
Separators       perform  concurrent  execution  of  commands,  or 

connect  the  input  or  output  of  one  command  to 

another  command. 
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Command  Lets  you  group  all  the  commands  that  you  want 
Grouping  affected  by  command  modifiers  or  separators. 

Note:  The  next  section,  "Command  Modifiers,"  provides 
details  on  these  features. 

Once  the  shell  identifies  the  keyword,  it  processes  any  modifiers. 
It  then  assumes  the  remaining  text  consists  of  parameters, 
which  it  passes  to  the  program  being  called. 

When  the  shell  receives  a  built-in  command,  it  immediately  exe- 
cutes it.  If  it  receives  a  command  that  is  not  built  in,  it  searches 
for  the  appropriate  program  and  then  runs  it  as  a  new  process. 
The  keyword  must  be  the  first  entry  in  any  line. 

While  the  program  is  running,  the  shell  deactivates  itself.  At  the 

termination  of  the  program,  the  shell  reactivates  and  accepts  the 
next  input.  This  cycle  continues  until  the  shell  detects  an  end-of- 
file  in  the  input  path.  It  then  terminates  its  own  execution.  You 
can  input  an  end  of  file  from  the  keyboard  by  pressing 
rsHirrpiiAK"]. 

Following  is  a  sample  shell  command  line  that  calls  the 

assembler. 


In  this  example: 


V 


v 


ASM  is  the  keyword. 

sourcefile,  1,  and  -o  are  the 

parameters     passed     to 

ASM. 

>/P   is   a   modifier   that 

redirects  the  output  (the 

listing)  to  the  system's 

printer. 

#12k  is  a  modifier  that 

asks  the  system  to  assign 

12K    bytes    of    memory 

instead  of  a  smaller  default 

amount 


sourcefile    1    -o    >/p   #12k 
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Command  Modifiers 

Add  command  modifiers  to  a  command  line  to  change  the  way  in 
which  the  command  functions.  Modifiers  let  you  tailor  OS-9  com- 
mands to  your  specifications.  Type  them  in  a  command  line  after 
the  keyword  and  either  before  or  after  other  parameters  you 
might  be  using. 

The  shell  processes  command  modifiers  before  it  executes  a  pro- 
gram. If  it  detects  an  error  in  any  of  the  modifiers,  it  stops  exe- 
cution and  reports  the  error. 

The  shell  strips  command  modifiers  from  the  part(s)  of  the  com- 
mand line  passed  to  the  program  as  parameters.  Therefore,  you 
cannot  use  the  characters  reserved  as  modifiers  (#;!<>&) 

inside  other  parameters. 

Execution  Modifiers 

Execution  modifiers  alter  the  amount  of  memory  commands  have 
available,  or  they  redirect  command  input  or  output. 

Alternate  Memory  Size  Modifier.  When  the  shell  invokes  a 

command  program,  it  allocates  the  minimum  amount  of  working 
RAM  (random  access  memory)  specified  in  the  program's  module 
header. 

Note:  All  executable  programs  include  a  module  header 
which  holds  the  program's  name,  size,  memory  require- 
ments, and  other  information.  For  information  on  viewing 
the  contents  of  a  module  header,  see  the  IDENT  command. 

You  might  want  to  increase  a  command's  default  memory  size. 
You  can  assign  memory  either  in  256-byte  pages  or  in  1024-byte 
increments.  To  add  memory  in  pages,  use  the  modifier  #?i,  where 
n  is  the  number  of  pages.  To  add  memory  in  1024-byte  incre- 
ments, use  the  modifier  #riK,  where  n  is  the  number  of  1024- 
byte  increments. 

The  following  two  examples  have  identical  results: 

copy  #8  filel    f  ilea    |  ENTER  |        (8x256     =  2048  bytes) 
copy  #2K  filel    file?  I  ENTER  |        (2x1024  =  2048  bytes) 
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I/O  Redirection  Modifiers.  Input/output  redirection  modifiers 
reroute  a  program's  I/O  from  the  standard  path  to  alternate  files 
or  devices. 

One  of  OS-9's  advantages  is  that  its  programs  use  standard  I/O 
paths  rather  than  individual,  specific  file,  or  device  names.  You 
can  easily  redirect  the  I/O  to  any  file  or  device  without  altering 
the  program  itself. 

Programs  that  normally  receive  input  from  a  terminal  or  send 
output  to  a  terminal  use  one  or  more  of  these  three  standard  I/O 
paths: 

•  Standard  input  path— Routes  data  from  the  terminal's 
keyboard  to  programs.  The  standard  input  path  is  Path 
Number  0. 

Use  the  less-than  symbol  (<)  to  redirect  data  to  this 
path. 

•  Standard  output  path — Routes  data  from  programs  to 
the  terminal's  display.  The  standard  output  path  is  Path 
Number  1. 

Use  the  greater-than  symbol  (>)  to  redirect  data  from 
this  path. 

•  Standard  error  output  path — Routes  routine  status 
messages  (prompts  and  errors)  to  the  terminal's  display. 
(The  name  error  output  path  is  somewhat  misleading, 
since  many  kinds  of  messages  in  addition  to  error  mes- 
sages travel  the  path.)  The  standard  error  path  is  Path 
Number  2. 

Use  two  greater-than  symbols  (>>)  to  redirect  data 
from  this  path. 

When  you  use  a  redirection  modifier  in  a  command  line,  follow  it 
immediately  with  a  pathlist  for  the  substitute  device.  For  exam- 
ple, you  can  use  LIST  to  redirect  the  contents  of  a  file  called 
Correspondence  from  the  terminal  to  the  printer,  by  typing: 

list    correspondence    >  /  p  |  ENTER  | 

The  shell  automatically  creates,  opens,  and  closes  files  referenced 
by  redirection  modifiers  as  needed.  The  system  immediately 
restores  normal  I/O  paths  at  the  completion  of  any  com- 
mand using  redirection  modifiers. 
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In  the  next  example,  the  shell  redirects  DIR's  output — a  list  of 
files  in  the  MEMOS  directory— to  the  file  /Dl/Savelisting: 


dir    /d0/memo5    >/d1  /savelisting  [  EMTER  j 
You  can  now  view  the  contents  of  Savelisting  by  typing: 


list     /d1 /savelisting  [ENTERj 

OS-9  displays  the  file  contents  in  a  format  similar  to  a  directory 
listing. 

Directory  of  /d0/memos 
CMOS       SYS        startup 
OSSBoot 

'You  can  use  one  or  more  redirection  modifiers  before  the  pro- 
gram's parameters,  after  the  program's  parameters,  or  both. 
However,  use  each  modifier  only  once  in  a  command. 

The  following  example  shows  how  you  can  use  all  of  the  redirec- 
tion modifiers  together  to  start  BASIC09  on  a  device  window  and 
redirect  all  input  and  output  to  it: 


basic 09    <>>>/w1     ENTER 


When  you  redirect  multiple  paths,  you  must  use  the  redirection 
symbols  in  the  proper  order  as  shown  here: 

Legal  Illegal 


<>  /wl  ><  /wl 

<>>  /wl  >><  /wl 

>>>  /wl  >><  /wl 

Command  Separators.  You  can  include  more  than  one  com- 
mand on  a  command  line  by  using  command  separators.  Com- 
mand separators  cause  multiple  commands  to  execute  either 
sequentially  or  concurrently,  depending  on  the  separator  you 
use. 

Sequential  execution  means  that  one  program  must  complete  its 
function  and  terminate  before  the  shell  lets  the  next  program 
execute.  Concurrent  execution  means  that  two  or  more  programs 
begin  execution  and  run  simultaneously. 
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Sequential  Execution  Using  the  Semicolon.  Using  a  semi- 
colon between  commands  on  one  line  causes  them  to  execute 
sequentially.  For  instance: 


copy    myflle    /d1/newfile;     dir    >/p  |  ENTER] 

This  command  causes  the  shell  to:  (1)  execute  the  COPY  com- 
mand, (2)  enter  a  waiting  state  until  COPY  terminates,  then 
awake,  and  (3)  execute  DIR. 

If  an  error  occurs  in  any  program,  the  shell  does  not  execute 
subsequent  commands,  regardless  of  the  state  of  the  SHELL 
command's  X  (stop  on  error)  option. 

Here  are  two  more  examples  of  commands  using  the  semicolon: 

copy    oldfile     newfile;     del     oldfile;     list     newfile 
I  ENTER  I 


dir    /dl/myfile;     list    temp    >/p;    del    temp  [ENTER] 

Commands  separated  by  semicolons  are  in  fact  separate  and 
equal  child  processes  of  the  shell. 

Note:  When  one  process  creates  another  process,  OS-9  calls 
the  creator  the  parent  process  and  the  created  process  the 
child  process.  The  child  can  become  a  parent  by  creating 
yet  another  process. 

Concurrent  Execution  Using  the  Ampersand.  You  can  use 

the  ampersand  (&)  to  cause  multiple  commands  to  run  at  the 
same  time.  Each  command  you  specify  runs  as  a  separate  child 
process  of  the  shell.  That  is,  for  each  process,  the  shell  creates  a 
separate  shell  to  handle  the  operation.  When  the  process  is  com- 
plete, the  child  shell  terminates,  or  dies. 

While  more  than  one  process  is  running,  OS-9  divides  execution 

time  equally  among  the  processes. 

The  number  of  programs  that  can  run  at  the  same  time  varies. 
It  depends  on  the  amount  of  free  memory  in  the  system  and  the 
memory  requirements  of  the  programs  being  executed. 

An  example  of  a  simple  command  line  using  the  &  separator  is: 


dir     >/p&  (ENTER  | 
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The  shell  begins  to  run  DIR,  sending  output  to  the  printer.  At 
the  same  time  it  displays  both  the  number  of  the  forked  process 
(DIR)  and  a  new  prompt,  like  this: 

&007 

QS9: 

To  fork  a  process  means  to  create  a  process  as  a  branch  of 

another  process — a  subroutine. 

After  using  the  ampersand  to  fork  a  background  process,  you 
can  then  enter  another  command,  which  the  shell  executes  while 
output  from  your  original  command  continues  to  go  to  the 
printer.  This  means  you  don't  waste  time  waiting  for  OS-9  to  fin- 
ish a  task.  At  times,  the  keyboard  might  not  seem  to  respond  to 
your  typing,  because  characters  do  not  appear  on  the  screen. 
However,  OS-9  stores  the  characters  in  the  keyboard  buffer  and 
displays  them  as  soon  as  the  shell  can  accept  input  again. 

If  you  have  several  processes  running  simultaneously  and  want 
information  about  them,  use  the  PROCS  command. 

Combining  Sequential  and  Concurrent  Executions.  You  can, 
if  you  want,  use  both  the  concurrent  and  sequential  command 
separators  in  one  command  line.  For  example: 

dir  >/p&  list  -filet*  copy  filel  file2;  del  temp 
I  ENTER  I 


Because  the  &  modifier  joins  the  DIR,  LIST,  and  COPY  com- 
mands, these  commands  run  concurrently.  But,  because  a  semi- 
colon precedes  the  DEL  command,  DEL  does  not  run  until  the 

other  commands  terminate. 

Using  Pipes:  The  Exclamation  Mark,  You  can  use  the  excla- 
mation mark  (!)  to  construct  pipelines  for  OS-9  commands.  Pipe- 
lines consist  of  two  or  more  concurrently  executing  programs 
with  standard  input  paths,  and  standard  output  paths  or  both, 
connected  to  each  other  with  pipes. 

Pipes  are  the  primary  means  of  transferring  data  from  process 
to  process.  They  are  vital  to  interprocess  communications.  Pipes 
are  first-in,  first-out  buffers,  or  holding  areas  for  data. 
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The  shell  automatically  buffers  and  synchronizes  I/O  transfers 
using  pipes.  A  single  pipe  can  direct  data  to  several  destinations 
or  readers,  and  can  receive  data  from  several  sources,  or  writers 
on  a  first-come,  first-serve  basis.  An  end-of-file  occurs  if  a  pro- 
gram attempts  to  read  from  a  pipe  when  writers  are  not  avail- 
able to  send  data.  Conversely,  a  write  error  occurs  if  a  program 
attempts  to  write  to  a  pipe  when  readers  are  not  available. 

Pipelines  are  created  by  the  shell  when  it  processes  an  input  line 
with  one  or  more  pipe  separators  (!).  For  each  pipe  separator,  the 
shell  directs  the  standard  output  of  the  program  on  the  left  of 
the  pipe  separator  to  the  standard  input  of  the  program  on  the 
right  of  the  separator.  The  shell  creates  an  individual  pipe  for 
each  pipe  separator  in  the  command  line.  For  example: 

update  (master file  !  sort  !  write report 

>/p  |  ENTER  | 

This  command  redirects  input  from  a  path  called  Master_file  to 
a  file  named  Update.  The  output  of  Update  becomes  the  input  for 
the  program  Sort.  The  output  of  Sort,  in  turn,  becomes  the  input 
for  the  program  Write_report.  Finally,  the  command  redirects 
output  from  Write_report  to  the  printer.  The  shell  executes  all 
programs  in  a  pipeline  concurrently.  The  pipes  synchronize  the 
programs  so  the  output  of  one  never  gets  ahead  of  the  input 
request  of  the  next  program.  This  synchronization  means  that 
data  cannot  flow  through  a  pipeline  any  faster  than  the  slowest 
program  can  process  it. 

Raw  Disk  Input/Output.  OS-9  has  a  special  pathlist  function 

to  perform  raw  physical  input/output  operations  on  a  disk.  The 
pathlist  consists  of  the  device  name,  immediately  followed  by  the 
"@"  character. 

This  command  causes  OS-9  to  treat  the  entire  diskette  in  Drive 
/DO  as  one  logical  file.  The  operation  reads  each  byte  of  each  sec- 
tor, without  regard  to  actual  file  structure.  Commands  such  as 
DIR,  ATTR,  and  MFREE  use  this  feature  to  access  sectors  of 
disks  that  are  not  part  of  file  data  areas,  such  as  header  sectors. 

Warning:  When  using  this  raw  access,  use  extreme  cau- 
tion. Because  you  can  write  on  any  sector,  you  can  easily 

damage  file  or  directory  structures  and  lose  data.  Using  @ 
defeats  any  file  security  and  record  locking  systems. 
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To  convert  a  byte  address  to  a  logical  sector  number  when  using 
@,  multiply  the  sector  number  by  256.  Conversely,  the  logical 
sector  number  of  a  byte  address  is  the  byte  address,  modulo  256. 

Command  Grouping 

You  can  enclose  sections  of  command  lines  in  parentheses  to  per- 
mit modifiers  and  separators  to  affect  an  entire  set  of  programs. 
The  shell  processes  the  material  in  the  parentheses  by  recur- 
sively calling  itself  to  execute  the  enclosed  command  list. 

For  example,  if  you  want  to  send  directory  listings  of  the  ROOT 
directory  of  Drive  /DO  and  then  the  ROOT  directory  of  Drive  /Dl 
to  the  printer,  you  can  type  either: 


dir    /d0     >/p;     dir    /d1     >/p  |  ENTER] 
or: 


(dir    /dfl;     dir    /d1  )    >  /  p  |  ENTER  | 

The  results  are  identical  except  that  the  system  keeps  the  printer 
continuously  in  the  second  example.  In  the  first  example,  another 
user  could  steal  the  printer  between  DIR  commands. 

You  can  group  commands  to  cause  programs  to  execute  both 
sequentially  and  concurrently  with  respect  to  the  shell  that  ini- 
tiated them.  For  instance: 

(del     filel;     del     file2;     del    f  ile3)«,  I  ENTER  I 


Here,  the  shell  does  the  overall  deleting  process  concurrently 
with  whatever  else  you  tell  it  to  do,  because  you're  using  &. 
However,  the  shell  deletes  the  three  specified  files  sequentially 
because  you're  using  semicolons  within  the  parentheses. 

Suppose  you  have  a  program  named  Makeuppercase  that  con- 
verts lowercase  characters  to  uppercase  and  a  program  named 
Transmit  that  sends  data  to  another  computer,  you  can  use  a 
command  line  like  this: 

t  di  r  cmds;  dir  sys)  !  makeuppercase  !  transmit 

The  shell  processes  the  output  of  the  first  DIR  command  and 
then  the  second.  It  sends  all  the  DIR  output  to  Makeuppercase, 
and  Transmit  sends  all  the  output  to  another  computer. 


3-9 


OS-9  Commands  Reference 


Shell  Procedure  Files 

The  shell  is  a  re-entrant  program.  This  means  it  can  be  simulta- 
neously executed  by  more  than  one  process.  Like  most  other  OS- 
9  programs,  the  shell  uses  standard  I/O  paths  for  routine  input 
and  output. 

OS-9's  shell  offers  you  a  special  feature,  a  time  and  effort  saver 
called  a  procedure  file.  A  procedure  file  is  a  related  group  of 
commands,  and  when  you  run  the  file,  you  execute  all  the 
commands. 

Other  names  for  procedure  file  processing  are  batch  and  back- 
ground processing.  A  procedure  file  becomes  new  input  for  the 
shell.  By  running  a  procedure  file,  you're  using  the  shell  to  cre- 
ate a  new  shell,  a  subshell  that  accepts  and  carries  out  the  com- 
mands in  the  procedure  file. 

Note:  If  you  plan  to  use  the  same  command  sequences 
repeatedly,  create  a  procedure  file  to  do  the  job  by  using 
BUILD. 

When  you  enter  any  command  line,  the  shell  looks  for  the  speci- 
fied program  in  memory  or  in  the  execution  directory.  If  it  can- 
not find  the  program  there,  it  searches  the  data  directory  for  a 
file  with  the  specified  name.  If  it  finds  the  file,  the  shell  auto- 
matically interprets  it  as  a  procedure  file,  and  creates  the  sub- 
shell,  which  executes  the  commands  listed  in  the  procedure  file. 

Procedure  files  can  also  let  the  computer  execute  a  lengthy 
series  of  programs  while  it  is  unattended,  or  even  while  it  is  run- 
ning other  programs. 

There  are  two  ways  to  run  a  procedure  file.  For  instance,  to  exe- 
cute a  procedure  file  called  Mailsequence,  type  either: 


shell    ma  i  1  sequence  [ENTERj 
or 


mai  lsequence  [  ENTER  | 

Both  commands  do  the  same  thing:  create  a  subshell  to  run  the 
commands  you've  built  into  your  Mailsequence  procedure  file. 

To  run  a  procedure  file  in  a  concurrent  mode,  use  the  ampersand 
(&)  modifier.  As  long  as  memory  is  available,  you  can  run  any 
number  of  files  concurrently. 
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You  can  even  build  procedure  fiies  to  sequentially  or  concurrently 
execute  other  procedure  files. 

Note:  If  you  use  procedure  files  to  run  programs  you  don't 
intend  to  monitor  closely,  you  can  redirect  standard  output 
and  standard  error  output  to  another  file.  Later  you  can 
review  the  file's  contents.  Output  redirection  eliminates  the 
annoying  output  of  shell  messages  on  your  terminal  at  ran- 
dom times. 

Built-in  Shell  Commands  and  Options 

The  shell  has  a  number  of  built-in  commands  and  options. 
Whenever  you  use  one  of  these  functions,  the  shell  executes  it 
without  loading  it  or  creating  a  new  process  to  execute  it. 

You  can  execute  built-in  functions  alone,  use  them  at  the  begin- 
ning of  a  command  line,  or  use  them  following  any  program  sep- 
arator. You  can  separate  adjacent  built-in  commands  by  spaces 
or  commas. 

The  built-in  commands  and  their  functions  are: 


CHD  pathlist 


CHX  pathlist 


EX  modname 


i  =  devname 


Changes  the  data  directory  to  the  directory 
specified  by  the  pathlist. 

Changes  the  execution  directory  to  the  direc- 
tory specified  by  the  pathlist. 

Directly  executes  the  module  named.  This 
function  deletes  the  shell  process  so  that  it 
ceases  to  exist  and  executes  the  new  module  in 
its  place.  Use  EX  to  replace  the  executing 
shell  with  the  program  specified  by  modname. 
You  can  also  use  EX  without  a  module  name 
to  eliminate  the  current  shell,  for  example,  a 
shell  you  initialized  in  a  window  (see  below). 

Makes  a  shell  an  immortal  shell.  This  means 
that  when  the  shell  ends,  due  to  an  EOF,  OS-9 
restarts  it.  Each  time  the  shell  restarts,  it  has 
the  same  data  and  execution  directories.  To 
kill  an  immortal  shell,  use  EX  to  "chain"  to  a 
null  process,  such  as: 


e  x     ENTER 
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w 
*  text 


kill  procID 

setpr  procID 
number 


-x 


P 
-P 


■t 


Waits  for  any  process  to  terminate. 

Allows  you  to  make  a  comment.  The  shell  does 
not  process  text  following  the  asterisk.  Use 
this  function  to  label  operations  in  a  procedure 
file. 

Stops  the  specified  process. 

Changes  the  specified  process's  priority 
number. 

Causes  the  shell  to  cease  operation  whenever 
an  error  occurs  (a  system  default). 

Causes  the  shell  to  continue  operation  when 
an  error  occurs.  Use  this  function  in  procedure 
files  to  enable  the  shell  to  continue  to  other 
commands  if  one  command  process  fails 
because  of  a  system  error. 

Turns  the  shell  prompt  and  messages  on  (a 
system  default). 

Inhibits  the  shell  prompt  and  messages.  Use 
this  option  in  procedure  files  to  disable  screen 
display.  Be  sure  to  turn  the  prompt  and  mes- 
sage function  back  on  afterward. 

Makes  the  shell  copy  all  input  lines  to  output. 
Use  this  function  with  a  procedure  file  to 
cause  command  lines  to  display  as  they 
execute. 

Sets  the  system  so  that  it  does  not  copy  input 
lines  to  output  (a  system  default). 


Running  Compiled  Intermediate 
Code  Programs 

Before  the  shell  executes  a  program,  it  checks  the  program  mod- 
ule's language  type.  If  it  is  not  6809  machine  language,  the  shell 
calls  the  appropriate  run-time  system  for  that  module. 
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Ebr  instance,  if  you  have  BASIC09  on  your  OS-9  system  and 

want  to  run  a  BASIC09  I-code  module  called  Adventure,  you  can 
type: 


basic09   adventure  |  ENTER  ] 
or: 


adventure  j  ENTER] 
or: 


runb    adventure  I  ENTER  I 


In  the  last  example,  the  shell  uses  the  RUNB  module  to  inter- 
pret the  Adventure  I-code  module. 
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Multiprogramming  and 
Memory  Management 


One  of  OS-9's  most  valuable  capabilities  is  multiprogramming — 
sometimes  called  timesharing  or  multitasking.  This  feature  lets 
your  computer  run  more  than  one  process  at  the  same  time. 
Multiprogramming  can  be  a  time  saving  advantage  in  many  sit- 
uations. For  example,  you  can  edit  one  program  while  the  system 
prints  another.  Or  you  can  use  your  Color  Computer  to  control  a 
household  alarm  system,  lighting,  and  heating  and  at  the  same 
time  use  it  for  routine  work  or  entertainment. 

OS-9  uses  multiprogramming  regularly  for  internal  functions. 
You  can  use  it  by  putting  an  ampersand  at  the  end  of  a  com- 
mand line.  Doing  this  causes  the  shell  to  run  your  command  as 
a  background,  or  concurrent,  task. 

To  run  several  processes  simultaneously,  OS-9  must  coordinate 
its  input/output  system  and  CPU  time  and  allocate  its  memory 
as  needed.  This  chapter  gives  you  some  basic  information  about 
how  OS-9  manages  its  resources  to  optimize  system  efficiency 
and  make  efficient  multiprogramming  a  reality. 

Processor  Time  Allocation 
and  Timeslieing 

CPU  time  is  the  most  precious  resource  of  a  computer.  If  the 
CPU  is  busy  with  one  task  it  cannot  perform  another.  For  exam- 
ple, many  processes  must  wait  for  you  to  enter  information  from 
the  terminal.  While  the  process  is  waiting,  your  computer's  CPU 
must  also  wait.  Your  computer  is  limited  by  your  typing  speed. 

On  many  systems  there  is  no  way  around  such  a  bottle  neck. 
However,  OS-9  is  more  efficient.  It  assigns  CPU  time  to  pro- 
cesses only  as  they  need  it. 

To  do  this,  OS-9  uses  timeslieing.  Timeslieing,  as  described  in 
the  following  paragraphs,  lets  all  active  processes  share  CPU 
time. 

A  real-time  clock  interrupts  the  Color  Computer's  CPU  60  times 
each  second.  The  interruption  points  are  called  ticks,  and  the 

spaces  between  ticks  are  called  timeslices. 
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OS-9  allocates  timeslices  to  each  process.  At  any  tick  it  can  sus- 
pend execution  of  one  process  and  begin  execution  of  another. 
This  starting  and  stopping  of  processes  does  not  affect  their 
execution. 

How  often  OS-9  gives  a  process  timeslices  depends  on  the  pro- 
cess's priority  relative  to  the  priority  of  other  active  processes. 
You  can  access  priority  using  a  decimal  number  from  0  through 
255,  where  255  is  the  highest  priority. 

OS-9  automatically  gives  the  shell  a  priority  of  128,  Because 
child  processes  inherit  their  parents'  priorities,  the  shell's  child 
processes  also  have  priorities  of  128,  You  can  find  a  process's 
priority  with  the  PROCS  command,  and  can  change  it  using  the 
SETPR  command. 

Tfou  cannot  compute  the  exact  percentage  of  CPU  time  assigned 
to  any  particular  process,  because  there  are  some  dynamic  vari- 
ables involved,  such  as  the  time  the  process  spends  waiting  for 
I/O  devices.  But  you  can  approximate  the  percentage  by  dividing 
the  process's  priority  by  the  sum  of  the  priority  of  all  active 
processes: 

process's  CPU  share  =  priority  of  the  process 

sum  of  the  priorities 
of  all  active  processes. 

Note:  Timeslicing  happens  so  quickly  that  it  looks  as  if  all 
processes  execute  simultaneously  and  continuously.  If,  how- 
ever, the  computer  becomes  overloaded  with  processing,  you 
might  notice  a  delay  in  response  to  input  from  the  termi- 
nal. Or,  you  might  notice  that  a  procedure  program  takes 
longer  than  usual  to  run. 

Process  States 

The  CPU  time  allocation  system  automatically  assigns  each  pro- 
cess one  of  three  states  that  describes  its  current  status.  Process 
states  are  important  for  coordinating  process  execution.  A  pro- 
cess can  have  only  one  state  at  any  instant,  although  state 
changes  can  be  frequent.  The  states  are: 

•  Active — Applies  to  processes  currently  able  to  work — 
that  is,  those  not  waiting  for  input  or  for  anything  else. 
These  are  the  only  processes  assigned  CPU  time. 
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•  Waiting — Applies  to  processes  that  the  system  suspends 
until  another  process  terminates.  This  state  allows  coor- 
dination of  sequential  process  execution.  The  shell,  for 
example,  is  in  the  waiting  state  during  the  execution  of  a 
command  it  has  initiated. 

•  Sleeping — Applies  to  a  process  suspending  itself  for  a 
specified  time,  or  until  receipt  of  a  signal.  (Signals  are 
internal  messages  that  coordinate  concurrent  processes.) 
This  is  the  typical  state  of  processes  waiting  for  input/ 
output  operations. 

The  shell  does  not  assign  CPU  time  to  sleeping  or  wait- 
ing processes.  It  waits  until  they  become  active.  The 
PROCS  command  gives  information  about  process  states. 

Creation  of  Processes 

If  a  parent  process  creates  more  than  one  child  process,  the  chil- 
dren are  called  siblings  with  respect  to  each  other.  If  you  exam- 
ine the  parent/child  relationship  of  all  processes  in  the  system,  a 
hierarchical  lineage  becomes  evident.  In  fact,  this  hierarchy 
resembles  a  family  tree.  (The  family  concept  makes  it  easy  to 
describe  relationships  between  processes.)  OS-9  literature  uses 
the  family  concept  extensively  in  describing  OS-9's  multipro- 
gramming functions.) 

OS-9's  fork  function  automatically  performs  the  sequence  of  oper- 
ations required  to  create  a  new  process  and  initially  allocate 
resources  to  it. 

If  for  any  reason,  fork  cannot  perform  any  part  of  the  sequence, 
the  system  stops  and  fork  sends  its  parent  an  error  code.  The 
most  frequent  reason  for  failure  is  the  unavailability  of  required 
resources  (especially  memory),  or  the  inability  of  the  system  to 
find  the  specified  program. 

A  process  can  create  many  processes,  subject  only  to  the  availa- 
bility of  unassigned  memory.  When  the  parent  issues  a  fork 
request  to  OS-9,  it  must  specify  certain  information: 

•  A  primary  module — The  name  of  the  program  to  be 
executed  by  the  new  process.  The  program  can  already 
be  present  in  memory,  or  OS-9  can  load  it  from  a  disk 
file  with  the  same  name. 
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•  Parameters — Data  to  be  passed  to  and  used  by  the  new 
process.  OS-9  copies  this  data  to  part  of  the  child  pro- 
cess's memory  area.  (Parameters  frequently  pass  file- 
names, initialization  values,  and  other  information.) 

The  new  process  inherits  some  of  its  parent's  properties, 
including: 

•  A  user  number— For  use  by  the  file  security  system  to 
identify  all  processes  belonging  to  a  specific  user.  (This 
is  not  the  same  as  the  process  ID,  which  identifies  a  pro- 
cess.) OS-9  obtains  this  number  from  the  system  pass- 
word file  when  a  user  logs  on.  The  system  manager  is 
always  User  0. 

•  Standard  input  and  output  paths— The  three  paths: 
input,  output,  and  error,  used  for  routine  input  and  out- 
put. Most  paths  can  be  shared  simultaneously  by  two  or 
more  processes. 

•  Current  directories — The  data  directory  and  the  execu- 
tion directory. 

•  Process  priority. 

As  part  of  the  fork  operation,  OS-9  automatically  assigns: 

•  A  process  ID,  a  number  in  the  range  1  to  255  that  iden- 
tifies the  process.  Each  process  has  a  unique  number. 

•  Enough  memory  to  support  the  new  process.  In  OS-9,  all 
processes  share  a  memory  address.  OS-9  allocates  a  data 
area  for  the  process's  parameters  and  variables  and  a 
stack  for  each  process's  use.  It  needs  a  second  memory 
area  in  which  to  load  the  process  if  it  does  not  reside  in 
memory. 
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In  summary,  each  new  process  has: 

•  A  primary  module 

•  Parameters 

•  A  user  number 

•  Standard  I/O  paths 

•  Current  directories 

•  A  priority 

•  An  ID  number 

•  Memory 

Basic  Memory  Management  Functions 

Memory  management  is  an  important  OS-9  function.  OS-9  auto- 
matically allocates  all  system  memory  to  itself  and  to  processes, 
and  also  keeps  track  of  the  logical  contents  of  memory  (the  pro- 
gram modules  that  are  resident  in  memory  at  any  given  time). 
The  result  is  that  you  seldom  need  to  bother  with  the  actual 
memory  addresses  of  programs  or  data. 

The  operating  system  and  each  process  have  individual  address 
spaces.  Each  address  space  has  the  potential  to  contain  up  to  64 
kilobytes  of  RAM  memory.  Using  memory  management  unit 
(MMU)  hardware,  OS-9  moves  memory  into  and  out  of  each 
address  space  as  required  for  system  operations. 

Although  each  unit  is  subject  to  the  64K  maximum  program 
size,  you  can  run  several  processes  simultaneously  and  utilize 
more  than  64K  overall.  The  system  logically  assigns  RAM  mem- 
ory in  256-byte  pages,  but  the  MMU's  hardware  block  size  is 
8K.  Each  of  these  physical  blocks  has  an  extended  address  that 
is  called  a  block  number.  For  example,  the  8K  physical  block 
residing  at  address  $3C0OO  to  $3DFFF  is  Block  Number  $3C. 

Within  an  address  space,  OS-9  assigns  memory  from  higher 
addresses  downward  for  program  modules  and  from  lower 
addresses  upward  for  data  areas.  The  following  chart  shows  this 
organization: 
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program  modules 
(RAM  or  ROM) 

highest  address 

unused  space 
(RAM  or  empty) 

data  areas 
(RAM) 

lowest  address 

Loading  Program  Modules  into  Memory 

When  performing  a  fork  operation,  OS-9  first  attempts  to  locate 
the  requested  program  module  by  searching  the  module  direc- 
tory, which  has  the  address  of  every  module  present  in  memory. 
The  6809  instruction  set  supports  a  type  of  program  called  re- 
entrant code,  which  means  that  processes  can  share  the  code  of  a 
program  simultaneously. 

Since  almost  all  OS-9  family  software  is  re-entrant,  the  system 
can  make  the  most  efficient  use  of  memory.  For  example,  suppose 
that  OS-9  receives  a  request  (from  a  process)  to  run  BASIC09 
(which  requires  22  kilobytes  of  memory),  but  has  already  loaded 
it  into  memory  for  another  process.  Because  the  software  is  re- 
entrant, OS-9  does  not  have  to  load  it  again  and  use  another 
22K  of  memory.  Instead  the  new  process  shares  the  original 
BASIC09  by  including  the  location  of  the  BASIC09  module  in  its 
memory  map. 

OS-9  automatically  keeps  track  of  how  many  processes  are  using 
each  program  module,  and  deletes  the  module  when  all  processes 
using  it  terminate. 

If  the  requested  program  does  not  yet  reside  in  memory,  OS-9 
uses  its  name  as  a  pathlist  (filename)  and  attempts  to  load  the 
program  from  disk. 
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Every  program  module  has  a  module  header  describing  the  pro- 
gram and  its  memory  requirements,  OS-9  uses  the  header  to 

determine  how  much  memory  the  process  needs  for  variable  stor- 
age. The  module  header  includes  other  information  about  its  pro- 
gram, and  is  an  essential  part  of  the  OS-9  machine  language 
operation. 

You  can  also  place  commands  or  programs  into  memory  using 
the  LOAD  command.  Doing  so  makes  the  program  available  to 
OS-9  at  any  time,  without  having  to  be  loaded  from  disk.  A  pro- 
gram is  physically  loaded  into  memory  only  if  it  does  not  already 
reside  there. 

LOAD  causes  OS-9  to  copy  the  requested  module  from  a  file  into 
memory,  verifying  the  CRC  (Cyclic  Redundancy  Check).  If  the 
module  is  not  already  in  the  module  directory,  OS-9  adds  it. 

If  the  program  module  is  already  in  memory,  the  load  process 
still  begins  in  the  same  way.  But,  when  OS-9  attempts  to  add 
the  module  to  the  module  directory  and  notices  that  the  module 
is  already  there,  it  merely  increments  the  known  module's  link 
count  (the  number  of  processes  using  the  module). 

When  OS-9  loads  multiple  modules  in  a  single  file,  it  associates 
them  logically  in  the  memory  management  system.  "Vfou  cannot 
deallocate  any  of  the  group  modules  until  all  modules  have  zero 
link  counts.  Similarly,  linking  to  one  module  within  a  group 
causes  all  other  modules  in  the  group  to  be  mapped  into  the  pro- 
cess's address  space. 

Deleting  Modules  From  Memory 

UNLINK  is  the  opposite  of  LOAD.  It  decreases  a  program  mod- 
ule's link  count  by  one.  When  the  count  becomes  zero  (presum- 
ing that  the  module  is  no  longer  used  by  any  process),  OS-9 
deletes  the  module,   deallocates   its  memory,   and  removes  its 

name  from  the  module  directory. 

Warning:  Never  use  the  UNLINK  command  on  a  program 
or  a  module  not  previously  installed  using  LOAD.  Unlink- 
ing a  module  you  did  not  LOAD  (or  LINK)  might  perma- 
nently delete  it  when  the  program  terminates.  The  shell 
automatically  unlinks  programs  loaded  by  fork. 
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Suppose  you  plan  to  use  the  COPY  command  ten  times  in  a  row. 
Normally,  the  shell  must  load  COPY  each  time  you  enter  the 
command.  But  if  you  load  the  COPY  module  into  memory  and 
then  enter  your  string  of  commands,  you  don't  have  to  wait  for 
the  system  to  load  and  unload  COPY  repeatedly.  When  you  fin- 
ish using  COPY,  use  UNLINK  to  unlock  the  module  from  mem- 
ory. The  sequence  looks  like  this: 

1  oad 
copy 
copy 
copy 
copy 
copy 
copy 
copy 
copy 
copy 
copy 
unlink 


copy  Q 

:nter  1 

f  ilel 
f  ile2 
f  ile3 

f  i  1  e  1  a  |  ENTER  | 
f  ile2a  |  ENTER  I 
f  ile3a  |  ENTER) 

f  ile4 

f  ile4a  | ENTER] 

fileS 
f  ile6 
f  ile7 

f  ile5a  |  ENTER  J 
f  i  1  e6a  |  ENTER  | 
f  ile7a  (ENTER] 

f  ile8 

f  i  1  e8a  [  ENTER  ] 

f  ile9 

f  i  1  e9a  |  ENTER  ] 

f  ilel  0    f  ilel  Ba  |  ENTER  | 
k     copy  (  ENTER  1 

It  is  important  to  use  UNLINK  when  you  no  longer  need  the 
program.  Otherwise,  the  program  continues  to  occupy  memory 
that  might  be  used  for  other  purposes. 

Warning:  Be  careful  not  to  unlink  modules  that  are  in  use, 
because  OS-9  deallocates  the  memory  used  by  the  module 
and  destroys  its  contents.  All  programs  using  the  unlinked 
module  crash. 

Loading  Multiple  Programs 

Because  all  OS-9  program  modules  are  position-independent,  you 
can  have  more  than  one  program  in  memory  at  the  same  time. 
Since  position-independent  code  (PIC)  programs  don't  have  to  be 
loaded  into  specific,  predetermined  memory  addresses  to  work 
correctly,  you  can  load  them  at  different  memory  addresses  at 
different  times. 

PIC  programs  require  special  types  of  machine  language 
instructions  that  few  computers  have.  The  ability  of  the  6809 
microprocessor  to  use  PIC  programs  is  a  powerful  feature  and 
one  of  the  greatest  aids  toward  multiprogramming.  You  can  load 
any  number  of  program  modules  until  available  system  memory 
is  full. 
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OS-9  automatically  loads  each  program  module  at  non-overlap- 
ping addresses.  {Most  operating  systems  write  over  the  previous 
program's  memory  when  loading  a  new  program.)  OS-9s  tech- 
nique means  that  you  do  not  need  to  be  concerned  with  absolute 
memory  addresses. 
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Useful  System  Information 
and  Functions 


The  OS-9  system  must  load  many  parts  of  the  operating  system 
during  startup  and  system  operation.  Therefore,  on  a  floppy  disk 

system,  you  must  keep  the  system  diskette  in  Drive  /DO. 

Two  files  used  during  the  system  startup  operation,  OS9Boot 
and  Startup,  must  remain  in  the  system  diskette's  ROOT  direc- 
tory. Other  files  on  the  system  diskette  are  organized  into  two 
directories:  CMDS  (commands)  and  SYS  (other  system  files).  You 
can  also  create  other  files  and  directories  on  the  system  diskette. 
OS-9  always  creates  the  initial  data  directory,  or  ROOT  direc- 
tory, when  you  format  a  diskette. 

File  Managers,  Device  Drivers,  and 

Descriptors 

The  bootstrap  (instructions  that  initialize  OS-9)  loads  a  file 
called  OS9Boot  into  RAM  memory  at  startup.  This  file  contains 
file  managers,  device  drivers  and  descriptors,  and  any  other  mod- 
ules that  permanently  reside  in  memory.  For  instance,  the 
OS9Boot  file  might  contain  these  modules: 

OS9p2  OS-9  Kernel 

INIT  System  Initialization  Table 

IOMan  OS-9  input/output  manager 

RBF  Random  block  (disk)  file  manager 

SCF  Sequential  character  (terminal)  file  manager 

PipeMan  Pipeline  file  manager 

Piper  Pipeline  driver 

Pipe  Pipeline  device  descriptor 

CC3IO  Keyboard/video  graphics  device  driver 

PRINTER  Printer  device  driver 

SIO  RS-232  serial  port  device  driver 

CC3Disk  Disk  driver 

DO,  Dl  Disk  device  descriptor 

TERM  Terminal  device  descriptor 

Tl  RS-232  serial  port  device  descriptor 

P  Printer  (parallel)  device  descriptor 

PI  Printer  (serial)  device  descriptor 
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Clock  Real-time  clock  module 

CC3GO         System  startup  process 
W  -  W7         Window  device  drivers  W,  Wl,  W2,  W3,  W4, 
W5,  W6,  W7 

OS-9  stores  the  modules  loaded  during  the  system  startup  with 
a  minimum  of  fragmentation.  To  include  additional  modules,  cre- 
ate new  bootstrap  files  using  the  OS9GEN  command  or  the 
CONFIG  program  supplied  with  OS-9.  You  cannot  unlink  a  mod- 
ule loaded  as  part  of  the  bootstrap. 

After  booting,  when  the  system  switches  the  boot  block  into  its 
own  address  space,  any  non-system  files  included  in  the  boot- 
strap decrease  the  memory  available  in  the  system  mode.  It  is 
best  to  place  optional  modules  in  a  separate  file  and  load  them 
as  part  of  the  system  startup  procedure.  One  example  is  the 
shell.  Never  include  the  shell  as  part  of  a  system  boot  file  in 
OS-9  Level  Two  systems. 

The  Sys  Directory 

The  OS-9  SYS  directory  contains  a  number  of  important  files: 

•  Errmsg  is  the  error  message  file. 

•  Stdfonts  contains  the  standard  software  fonts  for  use  on 
graphic  windows. 

•  STDPatterns  contains  screen  background  and  fill 
patterns. 

•  STDPtrs  contains  graphic  pointer  images  for  use  with  a 
mouse. 

These  files,  and  the  SYS  directory  itself,  are  not  required  to  boot 
OS-9,  but  you  do  need  them  if  you  plan  to  use  the  ERROR  com- 
mand, or  if  you  intend  to  use  text,  or  mouse  pointers  on  graphic 
windows.  You  can  also  add  other  system-wide  files  of  a  similar 
nature. 
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The  Startup  File 

The  Startup  file  (/DO/startup)  is  a  shell  procedure  file  that  OS-9 
automatically  processes  as  part  of  the  system  boot.  You  can 
include  any  legal  shell  command  line  in  the  Startup  file.  Many 
people  include  SETIME  to  start  the  system  clock.  If  this  file  is 
not  present,  the  system  starts  correctly,  but  the  system  time  is 
not  accurate. 


The  CMDS  Directory 

The  directory  /DO/CMDS  is  the  system-wide  command  directory 
normally  shared  by  all  users  as  their  working  execution  direc- 
tory. The  shell  resides  in  the  CMDS  directory.  The  system  start- 
up process  CC3go  makes  CMDS  the  initial  execution  directory. 
You  can  add  your  own  programs  to  the  CMDS  directory  and  have 
them  execute  in  the  same  manner  as  the  original  system 
commands. 


Making  New  System  Diskettes 

Getting  Started  With  OS-9  told  you  how  to  create  new  system 
diskettes  using  the  CONFIG  utility.  There  are  other  ways  to  cre- 
ate S3'stem  diskettes  and  either  add  or  subtract  capabilities.  The 
following  information  provides  guidelines  on  how  to  do  this.  For 
more  detailed  instructions  see  the  descriptions  of  the  CONFIG, 
OS9GEN,  and  COBBLER  commands  in  this  manual. 

Before  starting  any  of  the  following  procedures,  you  need  a 
blank,  formatted  diskette  on  which  to  place  your  system  files. 
Then,  choose  one  of  the  following  methods  to  update  your 
system: 

•  Use  the  OS9GEN  command  to  add  modules  to  the  exist- 
ing OS9Boot  file. 

•  Use  CONFIG  to  select  the  modules  you  want  to  include 
in  the  OS9Boot  file. 
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If  you  choose  to  use  CONFIG,  the  utility  creates  a  complete  sys- 
tem during  the  process.  If  you  use  OS9GEN,  follow  these  steps: 

1.  Create  the  OS9Boot  file  using  OS9GEN. 

2.  Create  or  copy  the  Startup  file. 

3.  Copy  the  CMDS  and  SYS  directories  and  the  files  they 
contain. 

You  can  perform  these  steps  manually  or  do  them  automatically 
by  using  one  of  these  methods: 

•  Creating  and  using  a  shell  procedure  file 

•  Using  a  shell  procedure  file  generated  by  DSAVE 
or 

•  Using  BACKUP 

Technical  Information  for  the  RS-232  Port 

You  can  operate  the  RS-232  port  or  the  printer  at  all  standard 
baud  rates  from  110  baud  to  19200  baud.  (The  default  rate  is 
600  baud.)  The  default  format  used  is  8  data  bits,  no  parity,  and 
1  stop  bit. 

Use  the  XMODE  command  to  set  the  port's  baud  rate,  parity, 
word  length,  stop  bits,  end-of-line  delay,  auto  line  feed,  and  so 
forth.  To  examine  the  printer's  current  settings,  type: 


xmode    /p  |  ENTER  | 

Then,  if  you  want  to  make  changes,  use  XMODE  with  informa- 
tion from  the  following  chart.  Select  the  parameter  you  want 
from  the  left  column  of  each  chart,  and  then  select  the  corre- 
sponding number  from  the  "Value  to  Use"  column  and  write  it 
down.  After  you  select  the  proper  value  from  each  chart,  add 
them  together  to  obtain  a  final  value  for  XMODE.  All  values 
must  be  hexadecimal. 
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Stop  Bits 


Word  Length 


Baud  Rate 


Number  of 
Stop  Bits 

Value 
to  Use 

1  Stop  Bit 

2  Stop  Bits 

0 

80 

Word 
Length 

Value 
to  Use 

7  Bits 

8  Bits 

20 

0 

Bits  Per 

Value 

Second 

to  Use 

110  BPS 

0 

300  BPS 

1 

600  BPS 

2 

1200  BPS 

3 

2400  BPS 

4 

4800  BPS 

5 

9600  BPS 

6 

19200  BPS 

7 

For  instance,  to  set  the  printer  parameters  to  one  stop  bit,  a 

word  length  of  seven  bits,  and  a  baud  rate  of  600,  select  0  from 
the  Stop  Bits  chart,  20  from  the  Word  Length  chart,  and  2  from 
the  Baud  Rate  chart.  Add  the  values  together: 

0  +  20  +  2  =  22 

The  command  to  set  the  printer  port  for  this  configuration  is: 


xmode    /p    baud  =  22  |  ENTER  ) 

When  you  use  XMODE  to  set  baud,  parity,  and  stop  bit  values, 
you  are  actually  setting  the  bits  of  a  special  byte  to  certain  val- 
ues. OS-9  uses  these  values  to  determine  how  to  handle  subse- 
quent input/output  operations.  A  bit  is  a  binary  digit  and  can  be 
either  1  or  0.  A  byte  consists  of  eight  bits  and  can  represent  a 
value  between  0  and  255. 

The  following  chart  shows  the  bits  that  control  baud  rate,  word 
length,  and  stop  bits  for  input/output  operations  on  a  specified 
device. 
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Bit 


7     6     5     4     3     2     10 

u 


->  Baud  rate 

->  Reserved 

->  Word  length 

->  Stop  bits 


If  the  stop  bit  value  =  0,  stop  bits  =  1 
If  the  stop  bit  value  =  1,  stop  bits  =  2 

If  the  word  length  value  =  00,  word  length  =  8  bits 

If  the  word  length  value  =  01,  word  length  =  7  bits 


If  the  baud  rate  value 
If  the  baud  rate  value 
If  the  baud  rate  value 
If  the  baud  rate  value 
If  the  baud  rate  value 
If  the  baud  rate  value 
If  the  baud  rate  value 
If  the  baud  rate  value 

(/t2  ACIAPAK  only) 
If  the  baud  rate  value 

(/tl  SIO  only) 


0,  baud  rate 

1,  baud  rate 

2,  baud  rate 

3,  baud  rate 

4,  baud  rate 

5,  baud  rate 

6,  baud  rate 

7,  baud  rate 


110 

300 

600 

1200 

2400 

4800 

9600 

19200 


=  8,  baud  rate  =  32000 


Use  XM0DE  TYPE  =  veiue  to  set  parity,  MDM  (modem)  kill,  and 
the  not  ready  delay.  Value  is  a  hexadecimal  value  you  calculate 
from  the  following  chart: 


Parity 

Type  of 

Value 

Parity 

to  Use 

None 

0 

Mark 

A0 

Space 

EO 

Even 

60 

Odd 

20 

MDM  Kill 


Not  Ready  Delay 


Kill 
Switch 

Value 
to  Use 

On 

Off 

10 

0 

Not  Ready 

Value 

Delay 

to  Use 

0  seconds 

0 

1  second 

1 

2  seconds 

2 

3  seconds 

3 

+ 

+ 

+ 

+ 

t 

♦ 

+ 

15  seconds 

F 
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Select  a  value  from  each  chart,  and  add  them  together  to  get  a 
final  TYPE  value.  For  instance,  to  select  even  parity,  MDM  kill 
off,  and  a  not  ready  delay  of  10  seconds,  select  these  values  and 
add  them; 

60  +  0  +  A  =  6A 

To  set  the  new  values,  type: 


xmode    /p    type  =  6a  [  ENTER  j 

The  following  chart  shows  the  bits  that  control  parity,  the 
modem  kill  switch,  and  the  not  ready  delay. 


Bit 


7     6     5     4     3     2     10 


->  Not  ready  delay 
(printer  only) 


->  MDM  kill  switch  (ACIAPAK/ 
MODPAK  devices) 


— >  Parity 

If  the  parity  value  is  000,  then  parity  =  none 

If  the  parity  value  is  101,  then  parity  =  MARK,  no  check 

If  the  parity  value  is  111,  then  parity  =  SPACE,  no  check 

If  the  MDM  kill  switch  value  is  0,  then  DCD  loss  =  no  kill 

If  the  MDM  kill  switch  value  is  1,  then  DCD  loss  =  kill 

The  value  of  the  not  ready  delay  bits  equals  the  number  of 
seconds  delay. 

For  more  information  on  setting  other  parameters,  such  as  the 
end-of-line  delay  (null  count),  see  the  XMODE  command  refer- 
ence in  Chapter  6. 


5-7 


Chapter  6 


System  Command  Descriptions 


This  chapter  contains  alphabetical  descriptions  of  the  commands 
supplied  with  OS-9.  Ordinarily,  you  call  the  commands  from  the 
shell,  but  you  can  also  call  them  from  most  other  programs  in 
the  OS-9  family— including  BASIC09  and  the  Macro  Text  Editor. 

Warning:  Do  not  attempt  to  use  OS-9  Level  One  commands 
with  the  OS-9  Level  Two  system  or  to  use  Level  Two  com- 
mands with  the  Level  One  system. 

Organization  of  Entries 

Each  command  entry  includes: 

•  The  name  of  the  command 

•  A  syntax  line,  which  shows  you  the  format  and  spelling 

to  use  when  you  type  the  command 

•  A  brief  definition  of  what  the  command  does 

•  Information  about  any  options  available  with  the 
command 

•  Notes  about  the  command  and  how  to  use  it 

•  One  or  more  examples  of  command  use 

Command  Syntax  Notations 

OS-9  requires  that  you  enter  the  various  parts  of  a  command  in 
the  correct  order  and  in  the  correct  format.  An  example  of  the 
proper  syntax  follows  the  command  name. 

The  syntax  line  always  begins  with  the  name  of  the  command. 
Occasionally,  that's  all  you  need  (except  for  pressing  [  enter  |).  But 
other  commands  either  require,  or  can  accept,  parameters  (vari- 
ables that  give  instructions  to  OS-9). 

Some  syntaxes  include  variables  (shown  in  italics)  that  you 
replace  with  specific  parameters.  For  instance,  the  BUILD  com- 
mand syntax  is: 


build    filename  1  ENTER  I 
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BUILD  is  the  command  name.  You  type  it  exactly  as  shown. 
However,  filename  is  a  variable.  Replace  it  with  the  actual  name 
you  want  to  give  to  the  file  you  are  creating.  If  you  want  to  cre- 
ate a  file  named  Myfile,  type: 


huild   myfile  [ ENTER ] 
Pressing  |  emter  [  executes  the  command. 
Common  variables  are: 


arglist 


arglist  (argument  list)  is  similar  to  paramlist, 
but  it  includes  command  names  as  well  as 
command  parameters. 


devname 

device  name  (/P,  /TERM,  /Ml) 

commandname 

command  name 

dirname 

directory  name 

filename 

file  name 

hex 

a  hexadecimal  number 

hhlmmlss 

hour/m  inutes/seconds 

modname 

name  of  a  memory  module 

n 

a  decimal  number 

number 

a  numeric  value 

opts 

options 

paramlist 

a  list  of  parameters 

pathlist 

a  complete  path  to  a  directory  or  file 

permission 

file  permission  abbreviations 

procID 

process  ID  number 

text 

a  string  of  characters 

tickcount 

a  numeric  value  representing  system  clock 
ticks 

value 

a  numeric  value 

yylmmldd 

year/month/day 
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[  ]  Brackets  indicate  that  the  material  within  them  is  optional 
and  not  necessary  for  the  execution  of  the  command, 

...  An  ellipsis  indicates  that  you  can  repeat  the  material  imme- 
diately preceding  the  ellipsis.  Ebr  instance,  [filename^...]  means 
that  you  can  specify  more  than  one  filename  to  the  command. 
Following  is  the  syntax  for  the  DISPLAY  command: 

display    hex  [...]  I  ENTER  | 

This  means  you  can  include  more  than  one  hex  number  with 
DISPLAY,  such  as: 

display  54  48  49  53  20  49  53  20  41  20  53  45  43 
52  45  54  20  4D  53  53  41  47  45  |  ENTER  | 

Command  syntaxes  do  not  include  the  shell's  built-in  options  (for 
instance  I/O  redirection)  because  the  shell  filters  out  its  options 
before  it  passes  the  command  line  to  the  program  being  called. 

Command  Summary 

This  section  describes  the  format  and  use  of  OS-9  commands. 
The  following  list  is  a  summary  of  these  commands: 

ATTR Changes  a  file's  attributes 

BACKUP Makes  a  copy  of  a  diskette 

BUILD Builds  a  text  file 

CHD Changes  the  working  data  directory 

CHX Changes  the  working  execution  directory 

CMP Compares  files 

COBBLER  . . .  Makes  a  bootstrap  file 

CONFIG Creates  a  system  diskette  to  your  specifications 

COPY Copies  data 

DATE Displays  the  system  date  and  (optionally)  the 

time 

DCHECK  ....  Checks  a  disk  file  structure 

DEINIZ Deinitializes  a  device  previously  initialized  with 

INIZ 

DEL Deletes  a  file  or  files 

DELDIR Deletes  a  directory's  files,  then  deletes  the 

directory 

DIR Displays  the  names  of  all  files  in  a  directory 

DISPLAY Displays  the  characters  represented  by  hexadeci- 
mal values 

DSAVE Generates  a  procedure  file  to  copy  files 
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EDIT  Calls  the  OS-9  Macro  Text  Editor 

ERROR Displays  a  description  of  the  last  error  code 

ECHO  Echoes  text  to  the  screen 

EX Causes  the  shell  process  to  execute  another 

process 
FORMAT  ....  Prepares  a  disk  for  data  storage 

FREE Displays  the  amount  of  free  space  on  a  disk 

HELP Displays  the  syntax  and  use  of  commands 

IDENT Displays  OS-9  module  identification 

INIZ Initializes  and  attaches  devices 

KILL Terminates  a  process 

LINK Links  a  module  into  memory 

LIST Lists  the  contents  of  disk  data  files 

LOAD Loads  a  module  into  memory 

MAKDIR  ....  Creates  a  directory 

MDIR Displays  the  names  of  the  modules  in  memory 

MERGE Copies  and  combines  files 

MFREE Displays  a  list  of  free  RAM 

MODPATCH . .  Makes  changes  to  a  module  in  memory 
MONTYPE  . . .  Establishes  the  type  of  monitor  in  use 

OS9GEN Builds  and  links  a  bootstrap  file 

PROCS Displays  the  names  of  the  current  processes 

PWD Displays  the  name  of  the  current  data  directory 

PXD Displays  the  name  of  the  current  execution 

directory 
RENAME  ....  Changes  the  name  of  a  file  or  directory 

SETIME Activates  and  sets  the  system  clock 

SETPR Sets  a  process's  priority 

SHELL Creates  a  child  shell  to  process  one  or  more 

commands 

TMODE Changes  the  terminal's  operating  mode 

TUNEPORT     Adjusts  the  loop  delay  for  the  baud  rate  of  /P  or 

/T  devices 

UNLINK Unlinks  memory  modules 

WCREATE  . . .  Creates  a  window 

XMODE Displays  or  changes  a  device's  initialization 

parameters 
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ATTR 


Syntax:      attr  filename  [permission] 

Function:    Lets  you  examine  or  change  a  file's  security 
permissions. 

Parameters: 

filename  The  name  of  the  file  you  want  to  examine  or 

change. 

permission         One  or  more  of  the  following  attribute  options. 

Options: 

The  file  permission  abbreviations  you  can  use  are: 

d  Specifies  that  a  file  is  a  directory. 

s  Specifies  that  the  file  is  not  shareable  and  can  serve 

only  one  user  at  a  time. 

r  Specifies  that  only  the  owner  can  read  the  file. 

w  Specifies  that  only  the  owner  can  write  to  (change) 

the  file. 

e  Specifies  that  only  the  owner  can  execute  the  file. 

pr  Specifies  that  the  public  (anyone)  can  read  the  file. 

pw  Specifies  that  the  public  (anyone)  can  write  to  the  file. 

pe  Specifies  that  the  public  (anyone)  can  execute  the  file. 

-a  Tells  ATTR  not  to  display  the  attributes.  Use.  this 

option   when  you  wish  to  change  attributes  without 
displaying  them. 
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Notes: 

•  To  use  ATTR,  type  the  command  name  followed  by  the 
name  of  the  file  you  want  to  change.  Next,  type  a  list  of  the 
permissions  to  turn  on  or  off.  Turn  a  permission  on  by  typ- 
ing its  abbreviation  or  off  by  typing  its  abbreviation  pre- 
ceded by  a  minus  sign.  ATTR  has  no  effect  on  permissions 
you  do  not  name. 

•  If  you  do  not  specify  any  permissions,  ATTR  displays  the 
file's  current  attributes. 

•  You  cannot  change  the  attributes  of  a  file  you  don't  own. 
User  0  can  change  the  attributes  of  any  file  in  the  system. 

•  Use  ATTR  to  change  a  directory  into  a  file  after  deleting 
all  the  directory's  files.  You  cannot  change  a  file  to  a  direc- 
tory with  ATTR.  (See  MAKDIR.) 

Examples: 

•  To  remove  public  read  and  write  permission  from  a  file 

named  Myfile,  type: 

attr    myfile    -pr     -pw  'ENTER  I 

•  To  give  read,  write,  and  execute  permission  to  everyone  for 
the  file  Myfile,  type: 

attr    myfile    r    w    e    pr    pw    p  e  |  ENTER] 

•  To  display  the  current  permissions  of  a  file  named  Datalog, 
type: 

attr    datalog  |  ENTER  | 
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BACKUP 


Syntax:      backup  [opts][devnamel][devname2] 


Function:  Copies  all  data  from  one  disk  to  another. 


Parameters: 

devnamel 

devname2 
opts 


The  drive  containing  the  disk  files  you  want  to 
back  up. 

The  drive  containing  the  disk  to  which  you 
want  to  transfer  the  files. 

One  or  more  of  the  following  options. 


Options: 


-v 


#nK 


Cancels  the  backup  if  a  read  error  occurs. 

Lets  you  backup  a  diskette  using  only  one 
drive. 

Tells  BACKUP  not  to  verify  the  data  written 
to  the  destination  diskette. 

Increases  to  n  the  amount  of  memory  that 
BACKUP  can  use.  Increasing  the  amount  of 
memory  assigned  to  BACKUP  speeds  the  pro- 
cedure, n  can  be  either  in  pages  of  256  bytes 
or  in  kilobytes  (1024  bytes).  Include  K  to  indi- 
cate kilobytes. 


Notes: 


BACKUP  performs  a  sector  by  sector  copy,  ignoring  file 
structures.  In  all  cases,  the  devices  specified  must  have  the 
same  format  (size,  density,  and  so  forth)  and  the  destina- 
tion disk  must  not  have  defective  sectors. 
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•  If  you  omit  both  device  names,  the  system  assumes  you  are 
copying  from  /DO  to  /Dl.  If  you  omit  only  the  second  device 
name,  OS-9  performs  a  single-drive  backup  on  the  specified 
drive. 

•  The  following  demonstrates  a  complete  backup  of  /DO  to 
/Dl.  In  the  example,  the  diskette  in  Drive  /Dl  is  a  format- 
ted diskette  with  the  name  MYDISK.  Scratched,  which 
appears  in  one  of  the  following  messages,  means  erased. 
Yoxi  type: 


backup  |  ENTER  | 

The  screen  display  and  your  input  are: 

Ready  to  BACKUP  from  /D0  to  /D1  ?:  fT|  |  ENTER  | 
MYDISK 

is  being  scratched 

?:  m 

Sectors  copied:  $0276 

Ver  i  f y  pass 

Sectors  verified:  $0276 

Following  is  an  example  of  a  single-drive  back  up.  BACKUP 
reads  a  portion  of  the  source  diskette  (the  diskette  you  are 
copying)  into  memory.  It  then  prompts  you  to  remove  the 
source  diskette  and  put  the  destination  diskette  (the 
diskette  receiving  the  copy)  into  the  drive. 

After  BACKUP  writes  to  the  destination  diskette,  remove 
the  destination  diskette  and  put  the  source  diskette  back 
into  the  drive.  Continue  swapping  as  prompted  until 
BACKUP  copies  the  entire  diskette. 

Giving  BACKUP  as  much  memory  as  possible  means  you 
have  to  make  fewer  diskette  exchanges.  If  enough  free  mem- 
ory is  available,  you  can  assign  up  to  56  kilobytes  for  the 
backup  operation.  An  Error  207  means  that  your  computer 
does  not  have  the  specified  amount  of  memory  free.  To 
assign  32  kilobytes  to  backup,  type: 


backup    /d0    #32k  I  ENTER  ] 
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The  screen  display  and  your  responses  are  as  follows: 

Ready  to  BACKUP  from  /D0  to  D0  ?:  (T) 

Ready  Destination,  hit  a 
MYDISK 
is  being  scratched 

?:  S 

Ready  Source,  hit  a  key: 

Ready  Destination,  hit  a 

Ready  Source,  hit  a  key: 

Ready  Destination,  hit  a 


k  ey  ; 

| ENTER  | 

|  ENTER  | 

key ; 
I  ENTER  I 

|  ENTER  | 

key : 

I  ENTER  | 

I 


Ready  Destination,  hit  a  key:  [ ENTER  1 

Sectors  copied:  $0276 

Ver  i  f y  pass 

Sectors  verified:  $0276 

In  this  procedure,  the  dollar  symbol  ($)  indicates  hexadeci- 
mal numbers.  BACKUP  copied  276  hexadecimal  (or  630 
decimal)  sectors. 


Examples: 


•  To  back  up  the  diskette  in  Drive  /D2  to  the  diskette  in 
Drive  /D3,  type: 


backup    /d2    /d3  [  ENTER  ) 

To  back  up  from  Drive  /DO  to  Drive  /Dl,  without  verifica- 
tion, type: 


backup    -v  [ ENTER  1 


6-9 


OS -9  Commands  Reference 


BUILD 


Syntax:       build  filename 


Function:  Builds  a  text  file  by  copying  input  from  the  stan- 
dard input  device  (the  keyboard)  into  the  file  specified  by 
filename. 


Parameters: 

filename  The  name  of  the  file  you  are  creating. 

Notes: 

•  BUILD  creates  a  file,  naming  it  filename.  It  then  displays  a 
question  mark  (?)  and  waits  for  you  to  type  a  line.  When 
you  type  a  line  and  press  I  enter  I,  BUILD  writes  the  line  to 
the  disk. 

•  When  you  finish  entering  the  lines  for  the  new  file,  press 
1  enter  1,  without  any  preceding  text,  to  close  the  file  and  ter- 
minate the  operation. 

•  The  following  example  demonstrates  how  to  build  a  text  file 
named  Newfile: 


huild    Tiewf  ile  (ENTER  I 


?    THE    POWERS    OF    THE    OS-9  rENTER] 


?    OPERATING    SYSTEM    ARE    TRULY  [ENTER] 


?    FANTASTIC.   rENTERl 


?     ENTER 


•  To  view  the  newly  created  file,  type: 


list    newfile  I  ENTER  I 
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The  screen  displays: 


THE  PDWERS  DF  THE  OS-9 
OPERATING  SYSTEM  ARE  TRULY 
FANTASTIC. 


Examples: 


To  create  a  new  file  called  Small—file  and  put  into  it  what- 
ever you  type  at  the  keyboard,  type: 


build    small_file    ENTER 


To  direct  whatever  you  type  to  the  printer,  type: 


build    /p  I  ENTER  | 

You  can  use  BUILD  to  transfer,  or  redirect,  data  from  one 
file  to  another.  Instead  of  the  keyboard,  this  example  uses  a 
file  named  My  text  file  for  the  input  device.  The  output 
device  is  Terminal  1. 


build    <mytext    /t1  I  ENTER  ) 
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CHD 
CHX 


Syntax:      chd  pathlist 
chx  pathlist 


Function:  CHD  changes  the  current  working  (data)  directory, 
and  CHX  changes  the  current  execution  directory. 


Parameters: 

pathlist  Specifies  the  directory  for  the  current  working 

or  execution  directory. 


Notes: 


CHD  and  CHX  do  not  appear  in  the  CMDS  directory 
because  they  are  built  into  the  shell. 


Examples: 


To  change  the  current  working  (data)  directory  to  the  PRO- 
GRAMS data  directory  located  on  the  diskette  in  Drive 
/Dl,  type: 


chd    /dl  /programs  |  ENTER  1 

•  To  change  the  execution  directory  to  the  parent  directory  of 
the  current  execution  directory,  type: 


chx      .  .      ENTERl 


To  change  the  execution  directory  to  TEXT—PROGRAMS, 
a  subdirectory  of  BINARY-FILES,  type: 

chx    binary — f  i  1  es/text—programs  f  ENTER  ) 
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To  return  the  execution  directory  and  the  data  directory 
back  to  the  default  directories,  type: 


chx    /d0/cmds;    chd    /d0  j  ENTER  | 
Or,  if  you  are  using  a  hard  disk,  type: 


chx    /h0/cmds;    chd    /h0  (JNTERJ 
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CMP 


Syntax:      cmp  filenamel  filename2 


Function:  Opens  two  files  and  compares  the  binary  values  of 
corresponding  data  bytes  in  the  files.  If  CMP  encounters  any 
differences  in  the  file,  it  displays  the  file  offset  (address)  and 
the  values  of  the  bytes  from  each  file. 


Parameters: 

filenamel  are  the  files  to  compare. 

fiiename2 


Notes: 

•  The  comparison  ends  when  CMP  encounters  an  end-of-file 
marker  in  either  file.  CMP  then  displays  a  summary  of  the 
number  of  bytes  compared  and  the  number  of  differences 
found. 

Examples: 

•  To  compare  two  files  named  Red  and  Blue,  type; 


cmp    red    blue  fEMTER ] 
Following  is  a  sample  screen  display: 
Di  f f erences 
byte  #1         #2 

00000013  00  01 

00000022  B0  B1 

0000002A  9B  AB 

0000002B  3B  36 

0000002C  8D  65 

Bytes  compared:   0000002D 
Bytes  different:  00000005 
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To  compare  two  files  that  are  identical,  such  as  Redl  and 
Red2,  type: 


cmp    redl     red2  |  ENTER  | 

The  screen  display  might  be: 
Differences 

None    ... 

Bytes  compared:   0000002D 
Bytes  different:  00000000 
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COBBLER 


Syntax:      cobbler  devname 


Function:  Creates  the  OS9Boot  file  required  on  any  OS-9  boot 
diskette. 


Parameters: 

devname  The  disk  drive  containing  the  diskette  on 

which  you  want  to  create  a  new  OS9Boot  file. 


Notes: 

•  COBBLER  creates  the  new  OS9Boot  file  with  the  same 
modules  loaded  during  the  most  recent  bootstrap.  (To  add 
modules  to  the  bootstrap  file,  use  OS9GEN.)  COBBLER 
also  writes  the  OS-9  kernel  on  Track  34  and  excludes  these 
sectors  from  the  diskette  allocation  map.  If  any  files  are 
present  on  these  sectors,  COBBLER  displays  an  error 
message. 

•  The  new  boot  file  must  be  contiguous  on  the  diskette.  For 
this  reason,  you  should  use  COBBLER  only  with  a  newly 
formatted  diskette.  If  you  use  COBBLER  on  a  diskette  that 
does  not  have  a  storage  block  large  enough  to  hold  the  boot 
file,  COBBLER  destroys  the  old  boot  file,  and  OS-9  cannot 
boot  from  that  diskette. 

•  To  change  device  attributes  permanently,  use  XMODE 
before  using  COBBLER. 


Examples: 

•  To  save  the  attributes  of  the  current  device  on  the  system 

diskette,  type: 


cobbler    /di  I  ENTER  I 
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If  you  use  COBBLER  on  a  diskette  that  is  not  newly  format- 
ted, the  screen  displays: 

WARNING    -    FILECS)    DR   KERNEL 
PRESENT    ON    TRACK    34    -    THIS 
TRACK    NOT    REWRITTEN 
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CONFIG 


Syntax:      config 


Function:  Lets  you  create  a  system  diskette  that  includes  only 
the  device  drivers  and  commands  you  select.  CONFIG  auto- 
matically adjusts  its  screen  display  for  either  32-  or  80-column 
display. 


Notes: 


When  executed,  CONFIG  displays  menus  of  all  I/O  options 
and  system  commands.  You  select  only  those  options  and 
commands  you  want  to  include  on  a  new  system  diskette. 

Creating  such  a  system  diskette  lets  you  make  the  most 
efficient  use  of  computer  memory  and  system  diskette 
storage. 

The  CONFIG  utility  is  on  the  BASIC09/CONFIG  diskette. 
Copy  this  diskette,  using  the  OS-9  BACKUP  command. 
Make  the  copy  your  working  diskette.  Keep  the  original  in 
a  safe  place  to  use  for  future  backups.  After  you  boot  your 
system,  you  can  put  the  working  copy  of  the  BASlC09/ 
CONFIG  diskette  in  drive  /dO.  Then,  type  these  commands: 


chx    /d0/cmds;     chd    /dB     ENTER 


CONFIG  does  not  require  initial  parameters.  You  establish 
parameters  during  the  operation  of  the  command.  Be  sure 
the  execution  directory  is  /DO/CMDS  before  executing 
CONFIG. 

You  could  save  time  by  using  BACKUP  to  create  a  system 
disk,  using  CONFIG  to  create  a  new  boot  file,  and  then 
deleting  unwanted  commands.  However,  this  process  causes 
fragmentation  of  diskette  space  and  results  in  slower  disk 
access.  CONFIG  causes  no  fragmentation. 
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•  The  MODULES  directory  of  the  BASIC09/CONFIG  diskette 
contains  all  the  device  drivers  and  device  descriptors  sup- 
ported by  OS-9.  The  filename  extension  describes  the  type 
of  file,  as  noted  in  the  following  table: 


Extension    Module  Type 


.dd  Device  Descriptor  module 

.dr  Device  Driver  module 

.io  Input/Output  subroutine  module 

.hp  Help  file 

.dw  Window  Device  Descriptor  module 

-dt  Terminal  Device  Descriptor  module 


Examples: 

The  following  steps  take  you  through  the  complete  CONFIG 
process: 

1.  With  the  BOOT/CONFIG  diskette  in  the  current  drive, 

type: 


conf  ig  [  ENTER  ] 

2.  CONFIG  asks  whether  you  want  to  use  one  or  two  disk 

drives.  Press  [JJ  for  single-  or  |T)  for  two-drive  operation. 

If  you  specify  one  drive,  continue  with  Step  3. 
If  you  specify  two  drives,  a  display  asks  you  to: 

ENTER    NAME    OF    SOURCE   DISK: 
Type  /d0  I  enter  I 
A  display  now  asks  you  to: 

ENTER    NAME    DF    DEST>    DISK: 
Type  /di  |  enter  I 

3.  After  a  pause  to  build  a  descriptor  list,  the  program  dis- 
plays a  list  of  the  various  devices  from  the  MODULES 
directory.  Use  [T]  and  2D  to  move  to  a  device.  To  include 
the  device  on  the  system  diskette,  press  fj]  once.  CONFIG 
displays  an  X  by  the  selected  device.  To  exclude  a  selected 
device,  press  (T|  again  to  erase  the  X. 
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A  special  help  command  provides  information  about  each 
device.  To  display  information  about  the  current  device  (the 
device  indicated  by  the  arrow  (-►)),  press  QT). 

The  list  of  devices  might  require  more  than  one  screen.  Use 
F*l  to  move  ahead  page  by  page  and  @  to  move  back. 

The  devices  you  can  select  and  their  descriptions  are  listed 
in  Chapter  2  under  the  section  "Device  Names." 

To  use  your  computer  keyboard  and  video  display,  you  must 
select  either  TERM_VDG  or  TERM_WIN.  You  use 
TERM_VDG  for  a  32-column  display.  For  windows  that 
enable  you  to  select  character  displays  up  to  80-columns, 
select  TERM_WIN.  You  must  select  a  "DO"  device  as  your 
first  disk  drive.  Select  from  the  list  of  D  devices  for  other 
floppy  disk  drives.  Select  P  to  use  a  printer  with  OS-9,  Tl 
to  use  a  terminal,  Ml  to  use  a  modem,  and  so  on. 

4.  After  selecting  the  devices  you  desire,  press  |T).  The  screen 
displays,  ARE  YOU  SURE  <Y/N)  ?  If  you  are  satisfied  with 
your  selections,  press  (T).  If  you  want  to  make  changes, 
press  (T). 

5.  CONFIG  builds  a  boot  list  from  the  selected  devices  and 
their  associated  drivers  and  managers  in  the  ROOT  direc- 
tory of  the  current  drive.  It  next  displays  two  clock  options: 

1  -  60hz  <American> 

2  -  S0hz  (European) 

6.  If  you  live  in  the  United  States,  Canada,  or  any  other  coun- 
try with  60hz  electrical  power,  press  QJ.  If  you  live  in  a 

country  with  50hz  power,  press  (T). 

If  you  have  a  single  disk  drive,  a  screen  prompt  asks  you  to 
swap  diskettes  and  press  (T|.  When  asked  for  the  SOURCE 
diskette,  insert  the  BASIC09/CONFIG  diskette.  When 
asked  for  the  DESTINATION  diskette,  insert  the  diskette 
that  is  to  be  your  new  OS-9  system  diskette. 

If  you  have  more  than  one  drive,  a  screen  prompt  asks  you 
to  insert  a  blank  formatted  diskette  (the  DESTINATION 
diskette)  in  the  destination  drive.  The  rest  of  the  boot  file 
creation  is  automatic. 
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7.  After  creating  the  boot  file,  CONFIG  displays  a  menu  of  the 
commands  you  can  include  on  your  system  diskette.  You 
have  the  following  choices: 

[NJo  Commands,  Stop  Now  —  Do  not  add  any  commands 
[FDull   Command  Set  — Add  all  OS-9  commands 

from  the  current  CMDS 

directory 
[  I  Dndividual  ly  Select       — Select  commands  one  by 

one 
C H ]    Receive   Help  —  Get  help  on  the  command 

set 

Press  Qjj  if  you  want  to  transfer  a  new  boot  file  to  a 
diskette  on  which  you  have  previously  copied  the  OS-9  sys- 
tem. If  you  have  only  one  disk  drive,  this  procedure  is 
quicker  than  using  the  CONFIG  utility  to  complete  the 
entire  system  transfer,  because  it  requires  fewer  disk 
swaps. 

Press  (T)  to  make  an  exact  copy  of  the  CMDS  directory  on 
your  source  diskette  with  a  new  boot  file. 

Press  ft)  to  individually  select  commands  to  copy  on  the 
new  diskette.  The  (JJ  option  displays  a  menu  similar  to  the 
device  selection  screen.  Press  (T)  to  select  or  exclude  com- 
mands, and  use  the  arrow  keys  to  move  among  the  com- 
mands in  the  menu.  CONFIG  selects  files  marked  with  an 
X  for  inclusion  on  the  new  system  diskette.  If  a  command 
does  not  have  an  X  beside  it,  CONFIG  excludes  it  from  the 
new  system  diskette. 

8.  If  you  have  a  multi-drive  system,  a  prompt  appears  asking 
you  to  insert  your  OS-9  system  diskette  in  the  destination 
drive.  Press  the  space  bar.  The  process  finishes  the  CON- 
FIG operation,  and  returns  to  OS-9. 

If  you  have  a  single-drive  system,  you  swap  diskettes  dur- 
ing the  final  process.  This  time,  the  SOURCE  diskette  is 
the  OS-9  System  diskette.  The  DESTINATION  diskette  is 

the  system  diskette  you  are  creating.  The  number  of  swaps 
depends  on  the  number  of  options  you  select. 

Note:  When  using  CONFIG  you  do  not  have  to  use 
your  system  diskette  as  the  source  diskette  to  install 
the  commands.  The  program  can  use  any  diskette 
that  contains  a  CMDS  directory. 
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COPY 


Syntax:      copy  [opts]  pathlistl  pathlist2 


Function:  Copies  data  from  one  file  or  device  to  another  file  or 
device. 


Parameters: 

pathlistl 

pathlist2 


The  name  of  the  existing  file  or  device  from 
which  you  want  to  copy. 

The  name  of  the  device  or  file  to  receive  the  copy. 
If  you  are  copying  data  to  a  file,  the  file  must  not 
already  exist. 


Options: 


-s 


#«LK] 


Causes  COPY  to  perform  a  single-drive  copy 
operation.  pathli$t2  must  be  a  full  pathlist  if  you 
use  -s.  In  a  single-drive  procedure,  COPY  reads 
a  portion  of  the  source  disk  into  memory  and 
then  asks  you  to  exchange  the  source  and  the 
destination  diskette  and  press  QT).  COPY  might 
ask  you  to  exchange  diskettes  several  times 
before  it  completes  duplicating  the  entire  file. 

Allows  the  use  of  more  memory  for  the  COPY 
procedure.  If  you  specify  K,  n  represents  the 
amount  of  memory  you  want  to  use,  in  units  of 
1024  bytes.  If  you  do  not  specify  K,  n  represents 
the  number  of  256-byte  memory  pages.  Using 
this  option  can  increase  speed  and  reduce  the 
number  of  diskette  swaps  required  for  single- 
drive  copies. 


6-22 


System  Command  Descriptions  I  6 


Notes: 


Tfpathlist2  is  a  disk  file,  COPY  automatically  creates  it.  Data 
can  be  of  any  type,  and  COPY  does  not  modify  the  file  in  any 
way, 

COPY  does  not  add  important  codes  (for  example,  line  feeds). 
Use  LIST  instead  of  COPY  when  sending  a  text  file  to  a  ter- 
minal or  printer. 

Following  is  an  example  of  the  screen  display  and  your 
responses  for  COPY  using  a  single  drive: 

copy    /d0/cnt    /d0/animel  s/cat    -s    #32k  |  ENTER  I 
Ready   DESTINATION,    hit    C    to    continue:  (T) 

Ready   SOURCE,    hit    C    to    continue:  QT) 
Ready   DESTINATION,    hit    C    to    continue:  QD 


This  example  assigns  32  kilobytes  of  memory  for  COPY  to 
use.  If  enough  free  memory  is  available,  you  can  specify  up 
to  56  kilobytes.  Copy  continues  asking  you  to  swap  the 
source  and  destination  diskettes  until  the  transfer  is 
complete. 


Examples: 


To  copy  Filel  to  File2  using  15K  of  memory,  type: 

copy  filel  file2  *15k  ["ENTER") 

To  copy  the  News  file  on  the  diskette  in  Drive  /Dl  to  a  new 
file  named  Messages  on  the  diskette  in  Drive  /DO,  type: 

copy    /d1/joe/new5    /dg/pe  ter  /messages  |  ENTER] 
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DATE 

Syntax:      date  |tj 

Function:  Displays  the  current  date. 

Options: 

t  Causes  the  time  to  appear  with  the  date. 

Notes: 

•  Following  is  an  example  of  how  to  use  SETIME  to  set  a  new 
date  and   time  for  the  system  and  how  to  use  DATE  to 

check  system  date  and  time: 


set  i me     ENTER 


A  possible  screen  display  and  your  responses  follows: 
yy/mm/dd    hh.mm.ss 


TIME?       86/08/22       14.19.00  I  ENTER  I 


date  I  ENTER  I 


August    22,    1986 


date    t     ENTER 


August    22,     1986    14.20.20 

Examples: 

•  To  display  the  system  date  and  time,  type: 


date    t     ENTER 


•  To  direct  the  DATE  command's  output  to  the  printer,  type: 


date    t     >/p  |  ENTER  | 
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DCHECK 


Syntax:      dcheck  [-opts]  devname 


Function:  Checks  a  disk's  file  structure. 


Parameters: 

devname 
opts 


The  disk  drive  to  check. 

One  or  more  of  the  following  options. 


Options: 


-s 


-b 

-P 

-Yf=pathlist 

-m 

-o 


Counts  the  number  of  directories  and  files  and 
displays  the  results.  This  option  causes 
DCHECK  to  check  only  the  file  descriptors  for 
accuracy. 

Suppresses  listing  of  unused  clusters  (clusters 
allocated  but  not  in  the  file  structure). 

Prints  pathlists  for  questionable  clusters. 

Specifies  a  path  to  a  directory  for  work  files. 

Saves  allocation  map  work  files. 

Prints  DCHECK's  valid  options. 


Notes: 


Sometimes  the  system  allocates  sectors  on  a  disk  that  are 
not  actually  associated  with  a  file  or  with  the  disk's  free 
space.  This  situation  can  happen  if  you  remove  a  disk  from 
a  drive  while  files  are  open.  You  can  use  DCHECK  to 
detect  this  condition,  as  well  as  check  the  general  integrity 
of  directory/file  links. 
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After  verifying  and  printing  some  vital  file  structure 
parameters,  DCHECK  follows  pointers  down  the  disk's  file 
system  tree  to  all  directories  and  files  on  the  disk.  As  it 
does  so,  it  verifies  the  integrity  of  the  file  descriptor  sec- 
tors, reports  any  discrepancies  in  the  directory/file  links, 
and  builds  a  sector  allocation  map  from  the  segment  list 
associated  with  each  file.  If  any  file  descriptor  sectors 
(FDS)  describe  a  segment  with  a  cluster  not  within  the  file 
structure  of  the  disk,  DCHECK  displays  a  message  like 
this: 

»*•  Bad  FD  segment  (t xxxxxx- Syyyyyy)    for  file: 
(pathlist) 

This  message  indicates  that  a  segment  starting  at  sector 
xxxxxx  and  ending  at  sector  yyyyyy  is  not  on  the  disk.  If 
any  of  the  file  descriptor  sectors  are  bad,  the  entire  FD 
might  be  defective.  DCHECK  does  not  update  the  alloca- 
tion map  for  corrupt  FDS. 

While  building  the  allocation  map,  DCHECK  also  ensures 
that  each  disk  cluster  appears  once  and  only  once  in  the  file 
structure.  If  it  discovers  duplication,  DCHECK  displays  a 
message  like  this: 

Cluster  % xxxxxx   was  previously  allocated 

This  message  indicates  that  DCHECK  has  found  cluster 
xxxxxx  more  than  once  in  the  file  structure.  DCHECK 
reprints  the  message  each  time  a  cluster  appears  in  more 
than  one  file. 

Then,  DCHECK  compares  the  newly  created  allocation  map 
with  the  allocation  map  stored  on  the  disk  and  reports  any 
differences  with  messages  like  these: 

Cluster  txxxxxx    in  allocation  map  but  not  in  file 
structure 

Cluster  txxxxxx    in  file  structure  but  not  in 
allocation  map 

The  first  message  indicates  that  sector  number  xxxxxx 
(hexadecimal)  is  not  part  of  the  file  system,  but  the  disk's 

allocation  map  has  assigned  it.  FORMAT  might  exclude 
some  sectors  from  the  allocation  map  because  they  are 
defective. 
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The  second  message  indicates  that  the  cluster  starting  at 
sector  xxxxxx  is  part  of  the  file  structure,  but  the  disk's 

allocation  map  has  not  assigned  it.  Later  operations  might 
allocate  this  cluster,  overwriting  the  contents  of  the  cluster 
with  data  from  the  newly  allocated  file.  (Clusters  that 
DCHECK  previously  allocated  can  have  this  problem.) 

•  DCHECK  builds  its  disk  allocation  map  in  a  file  called 
pathlistfDCJiECKppO,  where  pathlist  is  specified  by  the  -w 
option  and  pp  is  the  process  number  in  hexadecimal.  Each 
bit  in  this  bitmap  file  corresponds  to  a  cluster  of  sectors  on 
the  disk.  If  you  use  the  -p  option,  DCHECK  creates  a  sec- 
ond bitmap  file  (patfi/is*2/DCHECKppl)  that  has  a  bit  set 
for  each  cluster  DCHECK  finds  as  "previously  allocated"  or 
"in  file  structure  but  not  in  allocation  map."  DCHECK 
then  makes  another  pass  through  the  directory  structure  to 
determine  the  pathlists  for  these  questionable  clusters.  %u 
can  save  the  bitmap  work  files  by  specifying  the  -m  option 
on  the  command  line. 

•  For  best  results,  DCHECK  should  have  exclusive  access  to 
the  disk  being  checked.  Otherwise,  the  command  might  be 
fooled  by  a  change  in  the  disk  allocation  map  while 
DCHECK  is  building  a  bitmap  file.  DCHECK  cannot  pro- 
cess disks  with  more  than  39  levels  of  directories. 


• 


-p  causes  DCHECK  to  make  a  second  pass  through  the  file 
structure  and  print  pathlists  for  clusters  that  are  not  in  the 
allocation  map  but  are  allocated  or  existing  in  a  file 
structure. 

-w  tells  DCHECK  where  to  place  its  allocation  map  work 
file(s).  The  specified  pathlist  must  be  a  full  pathlist  for  a 
directory.  (DCHECK  uses  directory  /DO  if  you  do  not  spec- 
ify -w.)  If  you  doubt  the  structure  integrity  of  the  diskette 

being  checked,  do  not  place  the  allocation  map  work  files  on 
that  diskette. 


Examples: 


The  following  two  examples  demonstrate  DCHECK 
sessions: 


dcheck     /d2    ENTER  I 
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A  sample  screen  display  might  be: 

Volume  -  'My  system  disk'  on  device  /D2 

$009A  bytes  in  allocation  map 

1  sector  per  cluster 

$000276  total  sectors  on  media 

Sector  $000002  is  start  of  RQQT  directory 

FD 

$0010  sectors  used  for  id,  allocation  map 

and  RQQT  directory 

Building  allocation  map  work  file... 

Checking  allocation  map  file... 

'My  system  disk'  file  structure  is  intact 

1  directory 

2  files 


dcheck     -mpw=/d2    /d0  [  ENTER  ] 

A  sample  screen  display  might  be: 

Volume  -  'System  diskette'  on  device  /D0 

$0046  bytes  in  allocation  map 

1  sector  per  cluster 

$00022A  total  sectors  on  media 

Sector  $000002  is  start  of  ROOT  directory 

FD 

$0010  sectors  used  for  id,  allocation  map 

and  ROOT  directory 

Building  allocation  map  work  file... 

Cluster  #00040  was  previously  allocated 

**»  Bad  FD  segment  < $  1 1 1 1 1 1  - $23A6F0 )  for 

file:  /DB/TEXT/j unky.f ile 

Checking  allocation  map  file. . . 

Cluster  $000038  in  file  structure  but  not 

in  allocation  map 

Cluster  $00003B  in  file  structure  but  not 

in  allocation  map 

Cluster  $0001B9  in  allocation  map  but  not 

in  file  st  ructure 

Cluster  $0001BB  in  allocation  map  but  not 

in  file  structure 
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Pathlists  for  questionable  clusters: 


Cluster  $000038  in  path 
Cluster  $00003B  in  path 
Cluster  $000040  in  path 
Cluster  $000040  in 
double .file 


/d0/OS9boot 
/d0/OS9boot 
/d0/OS9boot 
path:    /dl 


/test/ 


1  previously  allocated  clusters  found 

2  clusters  in  file  structure  but  not  in 
allocation  map 

2  clusters  in  allocation  map  but  not  in 

file  structure 

1  bad  file  descriptor  sector 


"System  diskette'  file  structure   is 

i  n tac  t 

5  d  i  rec t or  i  es 

25  files 


not 
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DEINIZ 


Syntax:      deiniz  devname  [...] 

Function:   Deinitializes  and  detaches  a  device. 

Parameter: 

devname  The  name  of  one  or  more  devices  you  want  to 

deinitialize. 


Notes: 


Use  DEINIZ  with  INIZ.  For  example,  you  can  use  INIZ  to 
initialize  a  window,  then  redirect  information  to  the  win- 
dow. View  the  information  by  pressing  '  clear  |  until  it 
appears.  When  you  no  longer  need  the  window,  use  DEINIZ 
to  remove  the  window  and  return  its  memory  to  the 
system. 

DEINIZ  performs  an  OS-9  I$Detach  call  for  all  specified 
devices. 


Example: 

To  deinitialize  the  /wl  (Window  1)  device  after  it  has  been  ini- 
tialized, type: 


deiniz    w1  I  ENTER  I 
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DEL 


Syntax:      del  [-x]  filename  [...] 


Function:  Deletes  the  file(s)  specified. 


Parameter: 

filename 


The  name  of  the  file  to  delete.  Include  as  many 
filenames  as  you  want. 


Option: 

-X 


Causes  DEL  to  assume  the  file  is  in  the  cur- 
rent execution  directory. 


Notes: 

•  You  can  delete  only  files  for  which  you  have  write 
permission. 

You  can  delete  a  directory  in  two  ways:  (1)  Delete  all  the 
files  in  the  directory,  change  it  to  a  non-directory  file  using 
ATTR,  then  use  DEL  to  remove  the  directory,  or  (2)  Use  the 
DELDIR  command. 

•  The  following  example  shows  what  appears  on  the  screen 
when  you  display  a  directory,  delete  one  of  the  directory's 
files,  then  display  the  directory  again: 


dir    /c(1     ENTER 


directory  of  /D1  14.29.4S 

my f  i 1 e     newf  i le 


del    newf  ile  I  ENTER  I 


dir    /d1   I  ENTER  I 


directory  of  /D1  14.30.37 

my f lie 
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Examples: 

•  To  delete  files  named  TexLprogram  and  Test_program, 
type: 

del    text — program    test program  |  ENTER  | 

•  To  delete  a  file  on  a  drive  other  than  the  current  working 
drive,  use  a  complete  pathlist,  such  as: 


del     /dl  /number_f  ive  I  ENTER  I 


To  delete  a  file  named  Cmds.subdir  in  the  current  execu- 
tion directory,  type: 


del    -x    cmds.subdir  I  ENTER  I 
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DELDIR 


Syntax:      deldir  dirname 


Function:  Deletes  all  subdirectories  and  files  in  a  directory; 
then,  deletes  the  directory  itself. 


Parameter: 

dirname  The  pathlist  to  the  directory  you  want  to 

delete. 


Notes: 


DELDIR  is  a  convenient  alternative  to  individually  deleting 
all  the  files  and  subdirectories  from  a  directory  before 
deleting  the  directory  itself 

When  DELDIR  runs,  it  displays  a  prompt  after  the  com- 
mand line: 


deldir    oldf  iles  I  ENTER  I 


• 


Deleting  directory  file. 

List  directory,  delete  directory,  or  quit  ? 

(1/d/q) 

Pressing  |T)  causes  a  DIR  E  command  to  run  so  you  can 

see  the  directory  files  before  DELDIR  removes  them. 

Pressing  QD  starts  the  deletion  process. 

Pressing  fjT)  cancels  the  command. 

The  directory  to  be  deleted  might  include  other  directories, 
which  in  turn  might  include  other  directories,  and  so  forth. 
In  this  case,  DELDIR  begins  with  the  lower  directories  and 
works  its  way  upward. 

"Ifou  must  have  write  permission  to  delete  any  files  and 
directories  in  this  substructure.  If  not,  DELDIR  terminates 
when  it  encounters  the  first  file  for  which  you  don't  have 
write  permission. 
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•  DELDIR  automatically  calls  DIR  and  ATTR.  Therefore, 
these  files  must  reside  in  the  current  execution  directory. 
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DIR 


Syntax:      dir  [opts][dirname  or  pathlist] 


Function:  Displays  a  formatted  list  of  filenames  in  a  directory. 
The  output  format  adjusts  itself  for  80-  or  32-column  displays. 


Parameters: 

dirname  The  name  of  the  directory  you  want  to  view, 

pathlist  The  pathlist  to  the  directory  you  want  to  view. 

opts  Either  or  both  of  the  following  options. 

Options: 

If  you  don't  specify  any  parameters,  DIR  shows  the  current 
data  directory. 

x  Displays  the  current  execution  directory. 

e  Displays  the  entire  description  for  each  file: 

size,  address,  owner,  permissions,  date  and 
time  of  last  modification. 

Examples: 

•  lb  display  the  current  data  directory,  type: 


dir  I  ENTER  1 


•  To  display  the  current  execution  directory,  type: 


dir    x  |  ENTER  | 

lb  display  the  entire  description  of  all  files  in  the  current 
execution  directory,  type: 


dir    x    e  I  ENTER  I 
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To  display  the  parent  of  the  current  data  directory,  type: 


dir     .  .    I  ENTER  I 


To  display  a  directory  named  NEWSTUFF,  type: 


dir    news  tuff     ENTER! 


Following  is  a  sample  80-eolumn  DIR  display  using  the  e 
option: 


dir    e  I  ENTER  1 


The  screen  might  display: 
Directory  of    .  16:58:12 

Dwner    Last  modified    Attributes    Sector    Bytecount     Name 


2F 

85/85/28  1631 

*r 

A 

3A6C 

Q59Bosr. 

1 

85/85/28  1345 

d-ewrewr 

48 

G48 

CMDS 

1 

85/85/28  1358 

d-ewrewr 

i?; 

fiB 

SYS 

8 

85/85/28  135) 

r-wr 

132 

E 

startup 

i 

85/85/28  1351 

d-ewrewr 

194 

EB 

DEFS 

•  Following  is  an  80-eolumn  DIR  display  using  no  options: 


dir     ENTER 


The  screen  might  display: 

Directory  of   .  16:50:37 

DSSBoot     CMDS     SYS     startup 
DEFS 
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•  Following  is  a  32-column  DIR  display  using  the  e  option: 

dir    e  |  ENTER  | 

Directory  of   .  16:52:84 

Modified  on    Owner      Name 

ATTR        Sector      Size 

8S/0S/20  1643      2F    0S9Boot 

uir  A  3A6C 

85/05/20  1345       0    CMDS 
d-ewrewr         48         640 

85/05/20  13S0       0    SYS 
d-ewrewr         177  A0 

85/05/20  1351        0    startup 

r-wr         192  E 

85/05/20  1351       0    DEFS 
d-ewrewr        194  E0 

•  Following  is  a  32-column  DIR  display  using  no  options; 

dir  ;  ENTER  | 


Directory  of   .  16:52:29 
0S9Boot     CMDS      SYS 
startup     DEFS 
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DISPLAY 


Syntax:      display  hex  [.,.] 


Function:  Reads  one  or  more  hexadecimal  numbers  (you  type 
as  parameters),  converts  them  to  ASCII  characters,  and 
writes  them  to  the  standard  output  (normally  the  screen). 


Parameters: 

hex  A  list  of  one  or  more  hexadecimal  numbers. 

Notes: 

•  Use  DISPLAY  to  send  special  characters  (such  as  cursor 
and  screen  control  codes)  to  terminals  and  other  I/O 
devices. 

•  Following  is  an  example  of  a  command  and  the  resulting 
output,  ABCDEF  are  ASCII  characters  corresponding  to 
hex  41  42  43  44  45  46. 


display    41     42   43   44    45    46  |  ENTER  | 
ABCDEF 


Examples: 

•  Tb  reroute  a  form  feed  (hex  OC)  to  the  printer,  type: 


display    BC    >  /  p  [  ENTER  ) 
•  To  ring  the  bell  through  the  video  speaker,  type: 


display    07  |  ENTER  | 
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DSAVE 


Syntax:      dsave  [opts][devname][dirname]  >  pathlist 


Function:   Copies  or  backs  up  all  files  in  one  or  more 
directories. 


Parameters: 

devname 

dirname 

pathlist 
opts 


The  drive  on  which  the  source  directory  exists. 
If  you  do  not  specify  devname  DSAVE  assumes 
Drive  /DO. 

The  name  of  the  destination  directory.  Use 
CHD  to  make  the  current  directory  the  direc- 
tory to  receive  the  copies. 

A  command  procedure  file  in  which  DSAVE 
stores  its  output. 

One  or  more  of  the  following  options. 


Options: 

-b 

-i 
-1 

-m 

-sinteger 

-v 


Makes  the  destination  or  target  diskette  a  sys- 
tem diskette  by  copying  the  source  diskette's 
OS9Boot  file,  if  present. 

Indents  for  directory  levels. 

Tells  DSAVE  not  to  process  directories  below 
the  current  level. 

Tells  DSAVE  not  to  include  MAKDIR  com- 
mands in  the  procedure  file  it  creates. 

Sets  memory  for  the  copy  parameter  to  integer 
kilobytes. 

Verifies  copies  by  forking  to  CMP  after  copying 
each  file. 
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Notes: 


• 


DSAVE  does  not  directly  affect  the  system.  Instead,  it  gen- 
erates a  procedure  file  that  you  execute  later  to  do  the 

work. 

When  you  run  DSAVE,  it  creates  a  procedure  file  (a  file  of 

commands).  You  then  execute  the  newly  created  file  by  typ- 
ing its  pathlist.  The  procedure  contains  all  the  commands 
to  create  and  change  directories  as  needed  in  order  to  copy 
the  specified  directory.  DSAVE  copies  the  files  in  the  cur- 
rent data  directory.  It  also  copies  the  current  data  direc- 
tory subdirectories,  unless  you  specify  the  -1  option. 

To  use  DSAVE,  first  change  the  data  directory  to  the  direc- 
tory you  wish  to  copy.  Execute  DSAVE  by  specifying  the 
drive  from  which  to  copy  and  then  redirecting  output  to  a 
file  to  receive  the  copy  commands.  Be  sure  to  name  a  file 
that  does  not  already  exist. 

When  DSAVE  completes  the  procedure,  use  CHD  to  change 
to  the  data  directory  to  receive  the  copied  files.  Then,  exe- 
cute the  procedure  file. 

If  DSAVE  encounters  a  directory  file,  it  automatically 
includes  MAKDIR  and  CHD  commands  in  the  output 
before  generating  COPY  commands  for  files  in  the  subdirec- 
tory. The  procedure  file  exactly  replicates  all  levels  of  the 
file  system  from  the  current  data  directory  downward. 

If  the  current  data  directory  is  the  ROOT  directory  of  the 
disk,  DSAVE  creates  a  procedure  file  that  backs  up  the 
entire  disk  file  by  file.  This  is  useful  when  you  need  to  copy 
a  number  of  files  from  either  disks  formatted  differently  or 
from  floppy  diskettes  to  a  hard  disk. 


Examples: 


In  the  following  series  of  commands,  CHD  positions  you  in 
the  ROOT  directory  of  /D2,  the  directory  to  be  copied. 
Then,  DSAVE  makes  the  procedure  file  Makecopy.  Using 
CHD  /Dl  causes  the  copy  to  go  in  the  /Dl  ROOT  directory. 
The  final  command  executes  the  procedure  file. 
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chd    /d2  I  ENTER  ' 


dsave    /d2    >/d0/roakecopy  [INTER  ' 


chd    /d1  I  ENTER 


/d0/makecopy  [  ENTER  | 

The  following  command  copies  all  files  from  /DO  to  /Dl.  It 
pipes  the  procedure  file  output  of  DSAVE  into  a  shell  for 
immediate  execution. 


dsave      /d0       /d1       !       shell  I  ENTER  1 


The  following  command  lets  you  view  the  output  generated 
by  a  DSAVE  command.  It  uses  48  kilobytes  of  memory  and 
indents  directories.  Because  output  goes  to  the  screen,  this 
command  does  not  create  a  procedure  file  to  copy  any  files: 


dsave    -s48    -i  I  ENTER  I 


This  command  operates  in  the  same  manner  as  the  pre- 
vious command.  However,  because  it  specifies  a  procedure 
file  pathlist,  it  stores  the  generated  commands  in  a  proce- 
dure file  rather  than  displaying  them  on  the  screen: 


dsave    -s48    -i     >    copyf  ile  [  ENTER  ] 
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ECHO 

Syntax:      echo  text 

Function:  Echoes  text  to  the  screen. 

Parameters: 

text  The  character  or  characters  you  type. 

Notes: 

•  Use  ECHO  to  generate  messages  in  shell  procedure  files  or 
to  send  an  initialization  character  sequence  to  a  terminal. 
The  text  should  not  include  punctuation  characters  used  by 
the  shell. 

•  The  following  example  prints  the  message  LISTING  ERROR 
MESSAGES  to  the  screen  and  lists  the  file  SYS/errmsg  to  the 
printer  as  a  background  task. 

echo     LISTING     ERROR     MESSAGES;      list      sys/ 
errmsg    >/p&  |  ENTER  | 

Examples: 

•  To  display  a  message  on  the  screen,  type: 


echo    This     text     is    echoing  [  ENTER  | 

•  To  echo  text  to  the  console,  type: 

echo  >/term  **WARNING  DATA  ON  DISK  WILL  BE 
LDST!  I  ENTER  I 


•  The  following  combines  the  ECHO  and  LIST  commands  to 
echo  the  entered  text  to  the  printer  and  to  direct  the  con- 
tents of  the  Trans  file  to  the  printer. 

echo    >/p    LISTING    OF    TRANSACTION;     list    trans 
>/p4  |  ENTER  1 
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ERROR 


Syntax:      error  errnumber  [...] 


Function:  Displays  the  text  error  message  that  corresponds 
with  the  specified  OS-9  error  number. 


Parameters: 

errnumber  Is  an  OS-9  error  code  in  the  range  1-255, 

Notes: 

•  ERROR  opens  the  Errmsg  file  in  the  SYS  directory  and 
reads  through  the  file  for  an  error  code  that  matches  the 
specified  number.  It  then  displays  the  text  that  corresponds 
to  the  error  code. 

•  The  Errmsg  file  contains  descriptions  of  the  standard  OS-9 
errors.  The  order  of  the  file  is  arranged  to  provide  quick 
access  to  operation  system  error  descriptions. 

Example: 

•  To  display  a  description  of  the  OS-9  error  Numbers  215  and 
216,  type: 


error    215    216  j  ENTER  | 

The  screen  displays: 

215  -  Bad  Path  Name 

216  -  Path  Name  Not  Found 
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EX 


Syntax:      ex  filename 


Function:  Starts  a  process  by  chaining  from  the  current  shell 
to  the  new  process.  Chaining  means  that  execution  control  is 
turned  over  to  the  new  process. 


Parameters: 

filename  The  name  of  the  program  or  module  you  want 

to  execute. 


Notes: 


Using  EX  causes  the  shell  from  which  you  are  operating  to 
terminate.  If  the  new  process  also  terminates  and  you  do 
not  have  another  shell  running  on  another  terminal  or  win- 
dow, OS-9  is  left  without  any  processes,  and  you  must 
reboot  your  computer  and  OS-9. 

If  a  shell  is  running  on  another  window  or  device,  you  can 
restart  a  new  shell  from  that  window  or  device.  For 
instance,  if  you  use  EX  to  initialize  BASIC09  from  /TERM 
then  exit  BASIC09,  /TERM  is  dead  and  cannot  accept  key- 
board input.  However,  if  you  also  have  a  shell  operating  in 
a  window,  you  can  type  the  following  from  that  window: 


shell    i-/term4  I  ENTER  I 


This  reinitializes  a  shell  on  /TERM.  It  can  now  accept  key- 
board input  and  OS-9  commands. 

•  Use  EX  to  save  memory  when  the  shell  is  not  needed,  for 
instance  when  using  BASIC09. 
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•  If  you  use  EX  on  a  command  line  with  other  commands,  it 
must  be  the  last  command.  Any  commands  following  EX 
are  not  processed. 


Example: 

•  lb  run  BASIC09  without  a  resident  shell,  type: 


ex     basic09     ENTER 
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FORMAT 


Syntax:      format  devname  [opts\ 


Function:  Establishes  and  verifies  an  initial  file  structure  on 

a  floppy  diskette  or  a  hard  disk.  You  must  format  all  disks 
before  you  can  use  them  on  an  OS-9  system. 


Parameters: 

devname 

name 

opts 
Options: 


'cylinders' 
•interleave: 


The  drive  name  of  the  disk  you  want  to 

format. 

The  name  you  want  to  assign  the  newly  for- 
matted disk.  Enclose  the  disk  name  in  double 
quotation  marks. 

One  or  more  of  the  following  options. 


Causes  the  format  to  proceed  automatically, 
without  issuing  prompts. 

Formats  single-sided.  Use  with  single-sided 
drives  or  single-sided  diskettes  in  double-sided 

drives. 

Causes  a  double-sided  format.  Use  with 
double-sided  drives  and  double-sided  diskettes. 

The  number  of  cylinders  (in  decimal)  that  you 
want  formatted. 

The  number  of  the  sector  interleave  value  (in 
decimal). 
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Notes: 


Be  sure  the  disk  you  want  to  format  is  NOT  write- 
protected.  Otherwise,  FORMAT  generates  error  code  #242 
(write  protect),  and  the  system  returns  to  the  OS-9  prompt 
without  formatting  the  diskette. 

If  you  are  formatting  a  hard  disk,  first  type: 


tmode    -pause  |  ENTER  | 

This  command  turns  off  the  screen  pause  function.  Other- 
wise, the  process  stops  whenever  the  sector  verification  pro- 
cess fills  the  display  screen.  If  you  forget  to  turn  off  the 
screen  pause,  press  the  space  bar  whenever  the  screen  fills. 
Execution  then  continues. 

When  formatting  finishes,  type: 


tmode    pause  ;  ENTER  | 

This  re-establishes  the  screen  pause  function. 
The  formatting  process  works  this  way: 

1.  FORMAT  physically  initializes  a  disk  and  divides 
its  surface  into  sectors. 

2.  FORMAT  reads  back  and  verifies  each  sector.  If  a 

sector  fails  to  verify  after  several  attempts,  FOR- 
MAT excludes  it  from  the  initial  free  space  on  the 
diskette.  As  verification  proceeds,  the  process  dis- 
plays track  numbers. 

3.  FORMAT  writes  the  disk  allocation  map,  ROOT 
directory,  and  identification  sector  to  the  first  few 
sectors  of  Track  0.  These  sectors  must  not  be 

defective. 

FORMAT  asks  for  a  disk  volume  name,  which  can  be  up  to 
32  characters  long  and  can  include  spaces  or  punctuation. 
(Later,  you  can  use  the  FREE  command  to  display  the 
name.) 
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•  For  step-by-step  instructions  on  formatting,  refer  to  Getting 
Started  With  OS-9. 


Examples: 

•  To  format  a  diskette  in  Drive  /Dl,  type: 


format    /d1  I  ENTER  I 


To  format  a  diskette  in  Drive  /Dl  with  the  name  Test  Disk 
and  without  prompts,  type; 


format     /d1     r    "test     disk"  [ENTER] 

To  format  hard  Disk  /HO,  type: 


t 

mode 
orma  t 
mode 

-pause  I  ENTER  | 

f 

t 

/hi  i  ENTER] 
pause  |  ENTER  | 

To  format  a  double-sided  diskette  in  Drive  /D2  with  27  cyl- 
inders and  the  name  Database,  type: 


format     /d1     2    d    "database"     '27'  lENTER! 
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FREE 


Syntax:      free  drive 


Function:  Displays  the  number  of  unused  sectors  (256-byte 
storage  areas)  on  a  disk  drive.  These  sectors  are  available  for 
new  files  or  for  expanding  existing  files. 

Parameters: 

drive  The  disk  drive  for  which  you  want  to  display 

the  number  of  free  sectors. 


Notes: 

•  The  device  name  you  specify  must  be  a  disk  drive.  FREE 
also  displays  the  disk's  name,  creation  date,  and  cluster 
size.  If  you  don't  specify  a  drive,  FREE  selects  the  drive 
that  contains  the  current  data  directory. 

•  The  cluster  size  for  the  Color  Computer  is  one  sector. 

Examples: 

•  To  display  the  number  of  free  sectors  on  the  current  disk, 
type: 


free  !  ENTER  I 


The  screen  is  similar  to  this: 

"COLOR  COMPUTER  DISK"  created  on:  83/05/28 
Capacity:  630  sectors  (1-sector  clusters) 
15  Free  sectors,  largest  block  12  sectors 

To  display  the  number  of  free  sectors  on  the  diskette  in 
Drive  /Dl,  type: 


free    /d1   I  ENTER  I 
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A  sample  screen  display  is: 

DATA  DISK  created  on:  83/06/16 

Capacity:  630  sectors  (1-sector  clusters) 

445  Free  sectors,  largest  block  442  sectors 
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HELP 

Syntax:      help  command  name 

Function:  Displays  the  use  and  syntaxes  of  OS-9  commands. 

Parameters: 

command  The  command(s)  for  which  you  want  help. 

name  Include  as  many  command  names  as  you  want. 

Notes: 

•  HELP  uses  a  file  named  Helpmsg,  which  is  located  in  the 
SYS  directory  on  your  system  diskette. 

Examples: 

•  To  obtain  help  for  the  BACKUP  command,  type; 


help    backup  |  ENTER  | 

The  screen  displays: 

BACKUP    CeHsn-vHdevndev] 

Copies    all    data    from    one    device    to    another 

If  you  try  to  obtain  help  for  a  non-existent  command,  HELP 
displays  an  error  message.  For  instance,  if  you  type: 


help    me  |  ENTER  1 

ME    Help    not    available 

You  can  also  obtain  help  for  the  HELP  command.  To  do  so, 
type: 


help  |  ENTER  1 
The  screen  displays: 

HELP  [ command  name  J  I  ... ] 
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IDENT 


Syntax:      ident  name  [opts] 


Function:  Displays  header  information  for  memory  modules. 


Parameters: 

name 

opts 


The  name  of  the  file  or  module  for  which  you 
want  to  view  identification  information. 

One  or  more  of  the  following  options. 


Options: 


-m 


-v 


-X 


~s 


Causes  IDENT  to  assume  that  filename  is  a 
module  in  memory 

Tells  IDENT  not  to  verify  module  cyclic  redun- 
dancy check 

Causes  IDENT  to  assume  that  filename  is  in 

the  execution  directory 

Displays  the  following  module  information  on  a 
single  line:  the  edition  byte  {first  byte  after 
module  name),  the  type/language  byte,  the 
module  CRC  and  the  module  name.  A  period 
(.)  indicates  that  the  CRC  verifies.  A  question 
mark  (?)  indicates  that  the  CRC  does  not 
verify. 


Notes: 


IDENT  displays  the  module  size,  CRC  bytes  (with  verifica- 
tion), and — for  program  and  device  driver  modules — the  exe- 
cution offset  and  the  permanent  storage  requirement  bytes. 
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•  IDENT  displays  and  interprets  the  type/language  and 
attribute  revision  bytes.  IDENT  displays  the  byte  immedi- 
ately following  the  module  name  because  most  Microware®- 
supplied  modules  set  this  byte  to  indicate  the  module 
edition. 

•  IDENT  displays  all  modules  contained  in  a  disk  file. 

Examples: 

•  To  display  header  information  for  a  file  named  Ident  that 
resides  in  computer  memory,  type: 


ident     -m    ident  I  ENTER  1 


The  screen  might  display: 

Header  for:IDENT 

Module  size:      $0GE7     #1767 

Module  CRC:  $540BB2  (Good) 

Hdr  parity:  $C9 

Exec,  off:   $0233*573 

Data  size:   $099C#2460 

Edi  t  ion :  $07        #7 

Ty/la  At/Rv$11  $81 

Prog  mod,  6809  obj ,  re-en,  R/0 

In  the  example,  Hdr  parity  =  header  parity;  Exec,  off  = 
execution  offset;  Data  size  =  permanent  storage  require- 
ments; Edition  =  first  byte  after  module  name;  Ty/La/At/ 
Rv  =  type/language/attribute/revision;  and  Prog  mod,  6809 
obj,  re-en  =  module  type,  language,  attribute. 

To  display  header  information  for  the  OS9Boot  file,type: 


ident     /D0/DS9boot     -s  I  ENTER  I 


6-53 


OS -9  Commands  Reference 


The  display  might  include: 


1  7 

$C0 

$F2922F  . 

0S9p2 

67 

$C0 

$0B2322  , 

Init 

1  2 

$C1 

$2E9EDB  . 

IQMan 

27 

*D1 

$B6S5E3  . 

.  RBF 

6 

$E1 

$055580  . 

.  CC3Disk 

82 

$F1 

$FC1918  , 

.  D0 

82 

$F1 

I9F4210  . 

.  D1 

82 

$F1 

$E6B118  . 

.  DD 

1  1 

*D1 

$10A3FA  , 

.  SCF 

1  4 

$E1 

$8S24F1  , 

,  CC3I0 

1 

IC1 

$BS3D94  . 

,  VDGInt 

3 

$C1 

$792B7E  . 

.  Grflnt 

83 

$F1 

$AB5AE5  , 

.  TERM 

83 

$F1 

$7AB2DB  . 

.  W 

83 

$F1 

$C3E38A 

.  W1 

83 

$F1 

$948878 

.  W2 

83 

$F1 

$3G016B 

.  W3 

83 

$F1 

$0AE2B6 

.  N4 

83 

$F1 

$123B9A 

.  W5 

83 

$F1 

$1CF164 

.  W6 

83 

$F1 

$B71DFS 

,  W7 

1  1 

$E1 

$C8F073 

.  ACIAPAK 

82 

$F1 

$9E655D 

.  T2 

1  2 

$E1 

$CC3EA4 

.  PRINTER 

83 

$F1 

$FE3BAE 

.  P 

4 

$D1 

$AD6718 

,  PipeMan 

2 

$E1 

$5B2B56 

.  Pi  per 

80 

$F1 

SCC06AF 

.  Pipe 

9 

$C1 

$BE93F4 

.  Clock 

3 

$1  1 

$CA1F99 

,  CC3Go 

Since  the  -s  option  appears  in  the  command  line,  IDENT 
displays  each  module's  information  on  a  single  line.  In  the 
first  line  of  the  output,  for  instance,  1  =  edition  byte  (first 
byte  after  name),  $C0  =  type/language  byte,  $A366DC  = 
CRC  value,  .  =  OK  CRC  check,  and  OS9p2  =  module 
name. 
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INIZ 

Syntax:      iniz  devname  [...] 

Function:  Initializes  the  specified  device  driver. 

Parameters: 

devname  The  name  of  one  or  more  devices  to  initialize. 


Notes: 


• 


%>u  can  use  INIZ  in  the  Startup  file  or  at  the  system  start- 
up to  initialize  devices  and  allocate  their  static  storage  at 
the  top  of  memory  to  reduce  memory  fragmentation. 

INIZ  attaches  the  specified  device  to  OS-9,  places  the  device 
address  in  a  new  device  table  entry,  allocates  the  memory 
needed  by  the  device  driver,  and  calls  the  device  driver  ini- 
tialization routine.  INIZ  does  not  reinitialize  a  device  that 
you  or  the  system  previously  installed. 

If  you  change  the  printer  (/p)  to  a  non-shareable  device  (a 
device  that  is  not  re-entrant),  do  not  initialize  it  with  INIZ. 


Examples: 


To  initialize  the  /P  (printer)  and  /T2  (terminal  2)  devices, 
type: 


iniz    p    t2  |  ENTER  | 
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KILL 

Syntax:      kill  procID 

Function:  Terminates  the  process  specified  by  procID. 

Parameters: 

procID  The  ID  number  of  the  process  to  kill. 

Notes: 

•  Unless  you  are  the  Super  User  (User  Number  0),  you  can 

only  terminate  a  process  that  has  your  user  number.  (Use 
PROCS  to  obtain  the  process  ID  numbers.)  The  Super  User 
can  terminate  any  process. 

•  If  a  process  is  waiting  for  I/O,  you  cannot  cancel  it  until  the 
current  I/O  operation  terminates.  Therefore,  if  you  KILL  a 
process  and  PROCS  shows  it  still  exists,  it  is  probably  wait- 
ing to  receive  a  line  of  data  from  a  terminal. 

•  Because  KILL  is  a  built-in  shell  command,  it  does  not 
appear  in  the  CMDS  directory. 

Examples: 

•  To  KILL  the  process  with  the  ID  number  5,  type; 


kill     5  I  ENTER  j 

The  following  commands:  (1)  use  PROCS  to  determine  that 
the  ID  number  of  the  process  to  be  killed  is  3,  (2)  termi- 
nate process  3,  and  (3)  use  PROCS  to  confirm  that  KILL 
has  cancelled  the  process. 
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proc;  I  ENTER  | 

User  Mem  Stack 

Id    Fid  Number  Pty  Age  Sts  Signl  Siz     Ptr      Primary  Module 

2  1         8  128  128  $8?       8       3  J78B2  Shell 

3  5  8  128  128  $80        1        2  574AC  Tsman 

4  5  8  128  128  588        8        6  «SF3  Pro:s 

5  8  8  128  129  m        t        3  $6rE2  Shell 

HIl  3  .'  ENTER  j 
procs  I  ENTER  I 


User  Mem  Stack 

Id    PId  Number  =ty  Ag5  Sts  Signl  Siz    Ptr      Primary  Module 

I      '■■         0  128  128  188       8       3  $?8E2  Shell 

3      5  8  128  128  S88        8        6  385F3  ?rocs 

5      8  0  128  129  $88        8        3  56FE2  Shell 
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LINK 

Syntax:      link  modname 

Function:  Locks  a  previously  loaded  module  into  memory. 

Parameters: 

modname  The  name  of  the  memory  module  to  link. 


Notes: 


If  the  module  is  not  already  in  memory,  you  must  use 
LOAD  prior  to  using  LINK.  The  link  count  of  the  module 
increases  by  one  each  time  the  system  links  it.  Use 

UNLINK  to  unlock  the  module  when  you  no  longer  need  it. 


Examples: 

•  To  lock  the  Edit  module  into  memory,  type: 


link    edit  I  ENTER  I 
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LIST 

Syntax:      list  filename  [...] 

Function:  Lists  the  contents  of  a  text  file  or  files. 

Parameters: 

filename  The  name  of  the  file  you  want  to  list.  Include 

as  many  filenames  on  one  line  as  you  want,  up 
to  the  maximum  line  length  of  199  characters. 


Notes: 


LIST  copies  text  lines  from  a  file  to  the  standard  output 
path.  The  program  terminates  upon  reaching  the  end-of-file 
of  the  last  input  path.  If  you  specify  more  than  one  file, 
LIST  copies  the  files  in  the  order  in  which  you  list  them. 

Use  LIST  to  examine  or  print  text  files. 

Do  not  LIST  executable  files.  Doing  so  can  cause  your  sys- 
tem to  lock  or  crash.  To  view  executable  files,  use  DUMP. 


Examples: 

•  To  list  the  contents  of  the  Startup  file  to  the  printer,  type; 


list     /d0/startup    >/p&  |  ENTER] 

The  ampersand  makes  the  printing  job  a  concurrently  exe- 
cuted task. 

To  list  three  files  to  the  screen,  type: 

list  /d1 /user5/document  /d0/myfile   /d0/ 
bob/text  |  ENTER  | 

To  copy  everything  you  type  at  the  keyboard  to  the  printer, 
type: 


list     /term    >/p  [  ENTER  j 
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To  go  back  to  the  standard  output  path  (the  video  display) 
press  |  ctrl ||  break)- 

The  following  commands  create  a  file  called  Animals,  con- 
sisting of  six  entries.  LIST,  with  the  filename  Animals  as  a 
parameter,  displays  the  contents  of  the  new  file. 


build    animals  |  ENTER  I 


?    cat  (  ENTER  I 


?  cow  |  ENTER  1 

?  dog  |  ENTER  | 

?  elephant  |  ENTER  | 

?  bird  |  ENTER  | 


?    fish  |  ENTER  I 


?     ENTER] 


list    animals  |  ENTER  | 

The  screen  displays: 

cat 

cow 

dog 

elephant 

bird 

fish 
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LOAD 

Syntax:      load  pathlist 

Function:  Loads  a  module  (program)  from  a  file  into  memory. 

Parameters; 

pathlist  Specifies  the  module  to  load. 

Notes: 

•  LOAD  opens  the  path  you  specify,  then  loads  into  memory 
one  or  more  modules  from  it.  The  process  adds  the  names  of 
the  new  modules  to  the  module  directory.  If  LOAD  finds 
that  a  specified  module  has  the  same  name  and  type  as  a 
module  already  in  memory,  it  keeps  the  module  with  the 
highest  revision  level. 

•  If  the  pathlist  for  LOAD  does  not  include  a  drive  name, 
LOAD  uses  the  current  execution  directory.  To  LOAD  a 
module  from  a  directory  other  than  the  current  execution 
directory,  specify  a  full  pathlist,  beginning  with  a  drive 
name  if  applicable. 

Examples: 

•  In  the  following  example,  MDIR  displays  the  names  of  mod- 
ules currently  resident  in  memory.  Then,  LOAD  loads  the 
Edit  module  into  memory.  MDIR  again  lists  memory  mod- 
ules, and  this  time  shows  that  Edit  is  successfully  added  to 
memory. 

mdir  |  ENTER  | 


6-61 


OS-9  Commands  Reference 


The  screen  display  is  similar  to  the  following: 

Module  Directory  at  12:49:B2 


REL 

Boot 

0S9p1 

DS9p2 

Init 

IOMarn 

RBF 

CC3Disk 

D0 

D1 

DD 

SCF 

CC3I0 

VDGInt 

Grf  Int 

TERM 

W 

W1 

W2 

W3 

W4 

W5 

WB 

W7 

ACIAPAK 

T2 

PRINTER 

P 

Pi  peMan 

Pi  per 

Pipe 

Clock 

CC3Go 

CC3HDisk 

H0 

Shell 

Copy 

Date 

DEIniz 

Del 

Dir 

Display 

Echo 

I  n  i  z 

Link 

List 

Load 

MDir 

Merge 

Mfree 

Procs 

Rename 

Set  ime 

Tmode 

Unlink 

Bas  i c 

09 
edit 

GrfDrv 

load 

I  ENTER j 

md  i  r  ( 

ENTER 

I 

The  screen  displays: 

Module    Directory    at     12:51:12 


REL 

Boot 

QS9p1 

DS9p2 

Init 

IDMan 

RBF 

CC3Disk 

D0 

D1 

DD 

SCF 

CC3I0 

VDG I n  t 

Grf Int 

TERM 

W 

W1 

N2 

W3 

W4 

W5 

W6 

U7 

ACIAPAK 

T2 

PRINTER 

P 

Pi  peMan 

Piper 

Pipe 

Clock 

CC3Go 

CC3HDisk 

H0 

Shell 

Copy 

Date 

DEIniz 

Del 

Dir 

D  i  sp  lay 

Echo 

I  ni  z 

Link 

List 

Load 

MDir 

Merge 

Mfree 

Procs 

Rename 

Set  ime 

Tmode 

Unlink 

Baslc09 

GrfDrv 

Edit 
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MAKDIR 


Syntax:      makdir  pathlist  or  dirname 


Function:  Creates  a  directory  according  to  the  pathlist  given. 
You  must  have  -write  permission  for  the  parent  directory  of  the 
directory  you  are  creating. 


Parameters: 

pathlist  The  path  to  the  directory  you  want  to  create. 

dirname  The  name  of  the  directory  you  want  to  create. 

Notes: 

•  When  MAKDIR  initializes  the  new  directory,  the  directory 
contains  only  the  "."  and  ".."  files. 

•  MAKDIR  enables  all  permissions  for  the  directory  it 
creates. 

•  To  follow  OS-9  convention,  capitalize  all  directory  names. 

Examples: 

•  To  create  a  directory  on  Drive  /Dl,  use  the  directory's  full 
pathlist  from  the  root,  such  as: 


makdir     /d1 /STEVE/PROJECT    ENTER 


•  To  create  a  directory  called  DATAFILES  within  the  current 
data  directory,  type: 


makdir    DATAFILES    ENTER 


•  To  create  a  directory  called  SAVEFILES  in  the  parent  of 

the  current  directory,  type: 


makdir     .  .  /SAVEFILES  I  ENTER  I 
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MDIR 


Syntax:      mdir  [e] 


Function:  Displays  the  names  of  modules  currently  in  mem- 
ory. MDIR  automatically  adjusts  its  output  for  32-  or  80- 
column  displays. 


Options: 


Causes  a  full  listing  of  the  extended  physical 
address  (block  number  and  offset  within  the 
block),  size,  type,  revision  level,  re-entrant 
attribute,  user  count,  and  name  of  each  mod- 
ule. MDIR  shows  numbers  in  hexadecimal. 
The  display  adjusts  for  80  or  32  columns. 


Notes: 


Many  of  the  modules  displayed  by  MDIR  are  OS-9  system 
modules  and  are  not  executable  as  programs.  Always 
check  the  module  type  code  before  running  a  module 
with  which  you  are  not  familiar. 


Examples: 


Because  MDIR  adjusts  to  either  32  or  80  columns,  the  fol- 
lowing command  produces  a  full  module  listing  in  either 
format: 


mdir    e    ENTER  I 


The  80-column  display  of  MDIR  e  is: 
Module  Directory  at  83:83:53 

Block  Offset   Size  Typ  Rev  flttr     Use  Module  Name 

3F  Dae        12A     C1        1    r...  8  REl 
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3F 

E30 

1D0 

C1 

1  r... 

1 

Boot 

3F 

1808 

ED9 

CI 

8  r... 

I 

0S9p1 

1 

260 

CA1 

Cfl 

2  r... 

1 

□S9p2 

1 

EA1 

2E 

C0 

1  r... 

1 

Init 

! 

ECF 

993 

CI 

1  r... 

1 

IOMan 

*l 

1862 

122B 

D1 

1  r... 

6B 

RBF 

2A8D 

47G 

E1 

1  r... 

2 

CC3Disk 

2F83 

30 

Fl 

1  r... 

2 

D0 

2F33 

30 

Fl 

1  r... 

1 

D1 

2F63 

30 

n 

1  r... 

t 

DD 

2F93 

5B6 

D1 

1  r.. 

22 

SCF 

35-19 

B91 

E1 

1  r.. 

D 

CC310 

40Dft 

CE7 

C1 

1  p.. 

1 

VDGInt 

4DC1 

BF2 

CI 

1  p.. 

1 

Grflnt 

S9B3 

45 

F1 

1  p.. 

8 

TERM 

59F8 

42 

F1 

1  r.. 

t 

W 

SA3A 

43 

F1 

1  P.. 

0 

W1 

5A7D 

43 

Fl 

t  p. . 

0 

W2 

SAC0 

43 

F1 

1  p.. 

0 

W3 

SB03 

43 

F! 

1  r.. 

8 

W4 

SB46 

43 

Fl 

1  r.. 

8 

US 

5B89 

43 

Fl 

1  p.. 

8 

N6 

5BCC 

43 

F1 

1  P.. 

5 

W7 

SC0F 

3B5 

F1 

1  p.. 

8 

ACtAPAK 

5FC4 

3F 

F1 

1  p.. 

9 

T2 

6003 

17A 

E1 

1  p.. 

D 

PRINTER 

61  7D 

3C 

n 

1  p.. 

D 

P 

61 B9 

219 

D1 

1  p.. 

■  12 

PipeMan 

63D2 

28 

F1 

1  p.. 

12 

Pipep 

63FA 

2S 

Fl 

1  r.. 

12 

Pipe 

6420 

174 

C1 

1  r.. 

1 

Clock 

6594 

1AA 

11 

1  ... 

1 

CC3Go 

6 

I 

SF2 

11 

1  p.. 

3 

Shell 

G 

5F2 

2DC 

<  1 

1  r.. 

0 

Copy 

6 

8CE 

FD 

11 

1  r.. 

8 

Date 

6 

9CB 

78 

11 

1  P.. 

0 

DEiniz 

6 

A41 

AS 

11 

1  p.. 

0 

De. 

G 

AE6 

365 

11 

1  p.. 

0 

Dip 

6 

E4B 

84 

11 

1  p.. 

0 

Display 

6 

ECF 

22 

11 

1  p.. 

0 

Echo 

6 

EF1 

EA 

11 

1  p.. 

0 

Ini  z 

G 

FSB 

2C 

11 

1  r.. 

I 

Link 

6 

F87 

4F 

11 

1  P.. 

t 

List 

6 

FD6 

24 

11 

1  p.. 

0 

Load 

6 

FFA 

2F1 

11 

1  r.. 

1 

MDip 
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6 

12EB 

G8 

6 

1353 

1EB 

G 

153E 

319 

G 

185? 

11D 

G 

1974 

118 

G 

1 A8C 

301 

G 

1D8D 

2D 

8  Merge 

9  Mfree 
9  Procs 
9  Rename 
9  Setime 
0  Tmode 

9  Unlink 


The  32-column  display  of  MDIR  is: 


Module  Directory  at  03:06:49 
Blk  Dfst  Size  Ty  Rv  fit  Uc  Name 


3F      D06 

12ft 

C1 

r 

0 

REL 

3F      E30 

1D0 

C1 

r 

1 

Boot 

3F    1000 

ED9 

C0       8    r 

0 

DS9p1 

1       200 

CA1 

C0       2    r 

1 

DS9p2 

1       EA1 

2E 

C0 

r 

1 

Init 

1       ECF 

993 

CI 

r 

1 

IOMan 

1     1862 

122B 

D1 

r 

70 

RBF 

1     2A8D 

476 

E1 

r 

2 

CC3Disk 

1     2F03 

30 

F1 

r 

2 

D0 

1     2F33 

30 

F1 

r 

0 

D1 

1    2F63 

30 

F1 

r 

0 

DD 

1     2F93 

BB6 

D1 

r 

24 

SCF 

1     3549 

B91 

E1 

r 

D 

CC3ID 

1    40DA 

CE7 

CI 

r 

1 

VDGInt 

1    4DC1 

BF2 

C1 

r 

1 

Grf Int 

1     59B3 

45 

F1 

r 

8 

TERM 

1     S9F8 

42 

F1 

r 

0 

W 

1     5A3A 

43 

F1 

r 

0 

W1 

1     5A7D 

43 

F1 

r 

0 

W2 

1     5AC0 

43 

F1 

r 

0 

W3 

1     5B03 

43 

F1 

r 

0 

W4 

1     5B46 

43 

F1 

r 

0 

W5 

1     5B89 

43 

F1 

r 

0 

W6 

1     5BCC 

43 

F1 

r 

5 

W7 

1     5C0F 

3B5 

E1 

r 

A 

ACIAPAK 

1     5FC4 

3F 

F1 

r 

B 

T2 

1    6003 

17fl 

E1 

r 

D 

PRINTER 

1    61  7D 

3C 

F1 

r 

D 

P 

1    61  B9 

219 

D1 

r 

12 

PipeMan 

1     63D2 

28 

E1 

r 

1  2 

Piper 

1    63FA 

26 

F1 

r 

1  2 

Pipe 

1    6420 

174 

C1 

r 

1 

Clock 
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1 

6594 

1AA 

1 

1 

1 

CC3Go 

6 

0 

5F2 

1 

1 

r 

3 

Shell 

s 

SF2 

2DC 

1 

1 

r 

0 

Copy 

6 

8CE 

FD 

1 

1 

r 

a 

Date 

S 

9CB 

76 

1 

1 

r 

0 

DEInlz 

6 

A41 

AS 

1 

1 

r 

0 

Del 

G 

AE6 

3G5 

1 

1 

r 

0 

Dir 

G 

E4B 

84 

1 

1 

l- 

0 

Di  splay 

6 

ECF 

22 

1 

1 

r 

0 

Echo 

6 

EF1 

6A 

1 

1 

r 

0 

I  n  i  z 

6 

FSB 

2C 

1 

1 

r 

0 

Link 

G 

F87 

4F 

1 

1 

r 

0 

List 

G 

FD6 

24 

1 

1 

r 

0 

Load 

G 

FFA 

2F1 

1 

1 

r 

1 

MDir 

6 

12EB 

68 

1 

1 

r 

0 

Merge 

G 

1353 

1EB 

1 

1 

r 

0 

Mfree 

G 

153E 

319 

1 

1 

r 

0 

Procs 

G 

1857 

1  1D 

1 

1 

r 

0 

Rename 

6 

1974 

1  18 

1 

1 

r 

0 

Se  t  ime 

G 

1  A8C 

301 

1 

1 

r 

0 

Tmode 

6 

1D8D 

2D 

1 

1 

R 

0 

Unlink 
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MERGE 


Syntax:      merge  [ filename] [...] 


Function:  Copies  files  to  the  standard  output  path.  By  redi- 
recting the  output  of  the  MERGE  command,  you  can  combine 
several  files  into  one  file,  or  direct  several  files  to  the  printer. 


Parameters: 

filename  Specifies  the  files  to  combine. 

Notes: 


•  Use  MERGE  to  combine  several  files  into  a  single  output 
file.  It  copies  data  in  the  order  in  which  you  type  the 

filenames. 

•  MERGE  does  not  output  line  editing  characters  (such  as 
the  automatic  line  feed). 

•  You  normally  use  MERGE  to  redirect  the  standard  output 
to  a  file  or  device. 

•  You  can  use  MERGE  to  append  or  copy  any  type  or  mix- 
ture of  files  to  another  device. 


Examples: 

•  Tb  merge  four  files  into  a  new  file  called  Combined.file,  and 
send  the  results  to  the  new  file  instead  of  to  the  video  dis- 
play, type: 

merge  filel  file2  file3  file4  >combined . f i le 
I  ENTER  I 


To  merge  two  files,  and  send  the  output  to  the  printer,  type: 


merge    compile. list    asm. list     >  /  P  |  ENTER  | 
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MFREE 


Syntax:      mfree 


Function:  Displays  a  list  of  memory  areas  not  presently  in  use 
and,  therefore,  available  for  assignment. 


Notes: 


MFREE  displays  the  block  number,  physical  (extended) 
beginning  and  ending  addresses,  and  the  size  of  each  con- 
tiguous area  of  unassigned  RAM.  It  gives  the  size  in  num- 
ber of  blocks  and  in  kilobytes.  The  block  size  is  8  kilobytes 
per  block.  Free  memory  for  user  data  areas  does  not  need  to 
be  contiguous  because  the  MMU  can  map  scattered  free 
blocks  to  be  logically  contiguous. 


Examples: 

•  Type  this  command: 


mfree  I  ENTER  I 


The  screen  shows  a  display  similar  to  this: 
Blk    Begin      End      Blka      Size 


10 

12000 

10FFF 

1 

8K 

18 

18000 

1DFFF 

3 

24K 

20 

20000 

3FFFF 

1G 

128K 

Total:  20  160 
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MODPATCH 


Syntax:      modpatch  [options]  filename  [options] 

Function:  modifies  modules  residing  in  memory.  MODPATCH 
reads  a  patchfile  and  executes  the  commands  in  the  patehfile 
to  change  the  contents  of  one  or  more  modules. 


t 


Parameters: 

filename 

options 
Options: 


The  name  of  a  file  containing  instructions  for 
MODPATCH 

One  of  the  following  options  that  change  MOD- 
PATCH's  function 


-s 

-w 
-c 


Silent  mode,  does  not  display  patchfile  com- 
mand lines  as  they  are  executed. 

Does  not  display  warnings,  if  any 

Compares  only,  does  not  change  the  module 
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Notes; 

•  Before  using  MODPATCH,  you  must  create  a  patchfile  to 
supply  the  data  to  control  MODPATCH's  operation.  This  file 
contains  single-letter  commands  and  the  appropriate  mod- 
ule addresses.  The  commands  are: 


1  moduiename 


c  offset  origval  rewval 


Link  to  the  module  specified 
by  moduiename. 

Change  the  byte  at  the  offset 
address  specified  by  offset  from 
the  value  specified  by  origval 
to  the  new  value  specified  by 
newval.  If  the  original  value 
does  not  match  origval,  MOD- 
PATCH  displays  a  message. 

Verify  the  module — update  the 
modules  CRC.  If  you  plan  to 
save  the  patched  module  to  a 
file  that  the  system  can  load, 
you  must  use  this  command. 

Mask  IRQ's.  Turns  off  inter- 
rupt requests  (for  patching 
service  routines). 

u  Unmask  IRQ's.  Turns  on  inter- 

rupt requests  (for  patching 
service  routines). 

•  "%u  can  use  the  BUILD  command  or  any  word  processing 
program  to  create  patchfiles. 

•  Module  byte  addresses  begin  at  0.  MODPATCH  changes 
values  pointed  to  by  an  offset  address  (offset  from  0)  rather 

than  an  absolute  memory  address. 


m 


6-71 


OS -9  Commands  Reference. 


•  To  view  the  contents  of  a  memory  module,  use  SAVE  and 
DUMP  to  copy  the  module  to  a  file  and  display  its  contents. 
Also  use  SAVE  to  copy  the  patched  module  to  a  disk  file. 

•  Changing  a  memory  module  might  not  produce  an  immedi- 
ate effect.  You  have  to  duplicate  the  initialization  procedure 
for  that  module.  This  means,  if  the  module  loads  during 
bootup,  you  have  to  create  a  new  boot  file  that  includes  the 
changed  module,  then  reboot  using  the  new  boot  file. 

•  To  use  the  patched  module  in  future  system  boots,  use 
SAVE  to  store  the  module  in  the  MODULES  directory  of 
your  system  disk.  \bu  can  then  use  OS9GEN  to  create  a 
new  system  disk  using  the  patched  module.  If  you  are 

using  the  patched  module  to  replace  another  module, 
rename  the  original  module  and  then  give  the  patched 
module  the  original  name. 

•  If  you  patch  a  module  that  is  loaded  during  the  system 
boot,  you  can  use  COBBLER  to  make  a  new  system  boot 
that  uses  the  patched  module. 

Examples: 

The  following  example  shows  the  commands,  the  screen  prompts, 
and  the  entries  you  make  to  patch  the  standard  40-column  term 
window  descriptor  to  be  an  80-column  screen  rather  than  the 

standard  40-column  screen: 


0S9:build    termpatch  lENTER  j 
?     1     term  I7NTER"] 


?    c    002c    28    SO  [ENTER  1 
?    c    0030    01    02 


?    v  I  ENTER  I 


?     ENTER 


0S9:    modpatch    termpatch  [  ENTER  l 
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To  change  the  size,  columns,  and  colors  of  Device  Window  Wl, 
create  the  following  procedure  file  and  name  it  W180: 

I     w1 

c  0030  01  02 
c  002c  1b  50 
c  002d  Ob  18 

If  the  Wl  module  is  not  already  in  memory,  load  it  from  the 
MODULES  directory  of  your  system  disk.  Then,  before  initializ- 
ing Wl,  run  MODPATCH: 


modpatch    w180  |  ENTER  | 
Next,  initialize  Wl: 


iniz    w1     ENTER 


shell     i-/w1*    ENTER] 


Press  I  clear  I  to  display  the  new  window  with  80  columns,  24 
lines,  and  a  white  background. 


6-73 


OS-9  Commands  Reference 


MONTYPE 

J 

Syntax:      montype  type 

Function;  Sets  your  system  for  the  type  of  monitor  you  are 

using 

Parameters: 

Parameters: 

type  A  single  letter  indicating  the  monitor  type: 

c      for  composite  monitors  or  color  televisions 

r     for  RGB  monitors 

m    for  monochrome  monitors  or  black  and 
white  televisions 

..-'Notes: 

•  Different  types  of  color  monitors  display  colors  differently. 
For  the  best  results,  set  your  system  to  the  type  of  monitor 
you  are  using. 

•  If  you  are  using  a  monochrome  monitor  or  black  and  white 
television,  you  can  obtain  a  sharper  image  by  setting  your 
monitor  type  to  monochrome. 

•  Include  the  MONTYPE  command  in  your  system's  Startup 
file  to  automatically  boot  in  the  proper  monitor  mode. 

•  If  you  do  not  use  MONTYPE,  the  system  defaults  to  c  (com- 
posite monitor). 

Example: 

-•  To  set  your  system  for  an  RGB  monitor,  type; 


montype     r  [  ENTER  | 
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To  add  a  MONTYPE  command  to  your  existing  Startup  file,  first 
use  BUILD  to  create  the  new  command.  For  example: 


build    temp  |  ENTER  | 
montype    r  |  ENTER] 
[ENTER] 

Next,  append  the  file  to  Startup.  Type; 


merge    startup    temp    >    startup,  new  |  ENTER  | 

Delete  the  temp  file: 

del    temp  [ENTER] 

To  enable  the  system  to  use  Startup, new  when  booting,  rename 
the  original  Startup  file: 

rename  Startup  Startup. old 

Then  rename  Star  tup.  new: 

rename  Startup. new  Startup 
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OS9GEN 


Syntax:      os9gen  devname  [opts] 


Function:  Creates  and  links  the  required  OS9Boot  file  to  a 
diskette  making  it  a  bootable  diskette. 


Parameters: 

devname 

opts 
Options: 


The  disk  drive  containing  the  diskette  to 
receive  the  new  boot  file. 

One  or  more  of  the  following  options. 


-s 


#n[K] 


Causes  OS9GEN  to  use  only  one  drive  to  gen- 
erate the  boot  file.  In  a  single-drive  operation, 
OS9GEN  reads  the  modules  from  the  source 
diskette  and  asks  you  to  exchange  diskettes 
and  press  GO  as  it  reads  and  copies  the 
modules. 

reserves  n  kilobytes  of  memory  for  use  by  the 
OS9GEN  command.  By  setting  aside  as  much 
memory  as  possible,  you  can  increase  the 
speed  of  OS9GEN  and,  on  single-drive  sys- 
tems, reduce  the  number  of  diskette  swaps.  If 
you  type  K  after  #n,  the  memory  specified  by 
n  is  in  kilobytes  (1024  bytes),  otherwise  n  is 
in  256-byte  pages. 


Notes: 


OS9Boot  files  can  only  exist  on  contiguous  sectors.  There- 
fore, use  OS9GEN  only  with  newly  formatted  diskettes.  If 
OS9Boot  is  fragmented,  the  system  warns  you  not  to  use 
the  diskette  to  bootstrap  OS-9. 
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0S9GEN  creates  a  working  file  called  Tempboot  on  the 
device  specified  by  devname.  Next,  it  reads  filenames  (path- 
lists)  either  from  the  keyboard  {the  standard  input  path)  or 
redirected  from  a  file.  If  you  enter  names  manually, 
OS9GEN  does  not  display  a  prompt.  Type  each  filename 
and  press  [  enter  |.  After  typing  the  last  filename  and  press- 
ing |  enter  |,  press  [  enter  |  again,  or  press  [  ctrl  [|  break]  to  com- 
plete the  list. 

OS9GEN  opens  each  file  and  copies  it  to  Tempboot.  The 
process  repeats  until  it  reaches  a  blank  line  or  an  end-of- 
file  marker.  All  boot  files  must  contain  the  OS-9  component 
modules  listed  in  the  Chapter  5  section  "File  Managers, 
Device  Drivers,  and  Descriptors". 

You  must  have  RENAME  in  the  current  execution  directory 
or  in  memory  for  OS9GEN  to  work  properly. 

With  all  input  files  copied  to  Tempboot,  OS9GEN  deletes 
the  OS9Boot  file,  if  it  exists.  It  renames  Tempboot  as 
OS9Boot,  and  writes  the  file's  starting  address  and  size  in 
the  diskette's  Identification  Sector  (LSN  0)  for  use  by  the 
OS-9  bootstrap  firmware.  OS-9  writes  its  kernel  on  diskette 
Track  34.  If  there  is  not  room  for  the  kernel,  an  error  mes- 
sage appears,  and  the  operation  terminates. 

If  you  have  only  one  drive,  you  can  generate  a  new  boot  file 
more  easily  using  the  CONFIG  utility.  CONFIG  is 
designed  to  make  custom  system  diskettes  using  either  sin- 
gle- or  multiple-drives. 


Examples: 


The  following  commands  manually  install  a  boot  file  on 
device  /Dl  that  is  an  exact  copy  of  the  OS9Boot  file  on 
device  /DO.  The  first  command  line  runs  OS9GEN,  the  sec- 
ond enters  the  name  of  the  file  to  install,  and  the  third 
enters  an  end-of-file  marker. 


os9gen    /dl   |  ENTER  | 


/d0/os9boot  I  ENTER  I 


CTRL     BREAK 
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The  following  commands  let  you  manually  install  a  boot  file 
on  device  /Dl  that  is  a  copy  of  the  OS9Boot  file  on  device 
/DO  and  the  modules  stored  in  the  files  /DO/Tape.driver  and 
/D2/Video.driver.  Line  1  executes  OS9GEN.  Line  2  enters 
the  main  boot  filename.  Lines  3  and  4  enter  the  names  of 
the  two  additional  files,  and  Line  5  enters  an  end-of-file 
marker. 


os9gen    /d1  [  ENTER  | 


/d0/O59boot  I  ENTER  I 


/dU/tape.  driver  |  ENTER  | 


/d2/video. driver  I  ENTER  ] 


fCTRLlI  BREAK  | 

The  following  commands  generate  a  new  boot  file  on  Drive 
/Dl  that  includes  all  the  old  boot  file  functions.  Line  1  uses 
BUILD  to  create  a  file  called  Bootlist.  The  next  three  lines 
enter  the  names  of  the  three  files  within  Bootlist.  Line  5 
terminates  BUILD,  and  Line  6  runs  OS9GEN  with  input 
redirected  from  the  new  Bootlist  file. 


build     /d0/bootliat  I  ENTER  I 


?    /d0/os9boot  1  ENTER  I 


?    /dfl/tape.  driver  [  ENTER  | 


?    /dfl/video.driver  |  ENTER  | 
?    [  ENTER  I 


oaSgen    /d1 </dfl/boo t 1 i a t  j  ENTER  ] 

To  install  a  custom  boot  file  on  a  single-drive  system,  build 
a  Bootlist  to  drive  the  OS9GEN  program.  You  need  a  direc- 
tory that  contains  the  required  file  managers,  device  driv- 
ers, descriptors,  and  other  files  for  the  boot  file.  For 
example,  to  make  a  new  boot  file  containing  only  the 
/TERM,  /DO,  /Dl,  and  /P  devices,  first  build  a  Bootlist  such 
as: 
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build    /dB/bootlist  I  ENTER  | 
?    term_vdg,dt  |  ENTER  | 
?    p.dd  |  ENTER] 

? 
7 

? 
7 

d0_35a.dd  |  ENTER  | 
d1_3Ss  .dd  [ENTER) 
os9p2  I  ENTER  | 
Init  [ENTER] 

7 

IQMan  |  ENTER  I 

? 

RBF.mn  (  ENTER  | 

? 
? 
7 

CC3Dlsk  .dr  |  ENTER  ] 
SCF.mn  |  ENTER  | 
CC3I0.dr  |  ENTER  | 

7 

vdgint  .  lo  [ENTER] 

? 
? 
? 
? 

grf  int.  io  |  ENTER  | 
printer  .dr  |  ENTER  | 
clock  .60 hz  |  ENTER  | 
Cc3qo  I  ENTER  | 

Then  use  OS9GEN  to  create  the  new  boot  file  on  a  separate 
diskette  by  typing: 


os9gen    /d0    -s    *25K    </d8/boot  list  (ENTERl 

This  command  causes  OS9GEN  to  use  only  one  drive,  25K 
of  buffer  space,  and  the  filenames  previously  stored  in  the 
Bootlist  file. 

You  can  expand  this  basic  bootlist  file  to  include  other  stan- 
dard OS-9  modules  such  as  window  device  drivers,  other 
disk  drivers,  graphic  drivers,  and  so  on.  Or,  you  can  add 
device  descriptors  and  device  drivers  of  your  own,  that 
become  part  of  the  directory  of  modules  loaded  into  OS-9 
during  boot. 

All  of  the  standard  bootlist  modules  are  contained  in  the 
MODULES  directory  on  the  BASIC09/CONFIG  diskette. 
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PROCS 


Syntax:      procs  [e] 


Function:  Displays  a  list  of  the  processes  running  on  the  sys- 
tem. PROCS  automatically  adjusts  its  output  for  32-or  80- 

column  displays. 


Options: 


Causes  PROCS  to  display  the  processes  of  all 
users. 


Notes: 

•  Normally  PROCS  lists  only  processes  having  the  user's  ID. 
The  list  is  a  snapshot  taken  at  the  instant  PROCS  exe- 
cutes. Processes  switch  states  rapidly,  usually  many  times 
per  second, 

•  PROCS  shows  the  user  and  process  ID  numbers,  priority, 
state  (process  status),  memory  size  (in  256  byte  pages),  pri- 
mary program  module,  and  standard  input  path. 

•  PROCS  adjusts  its  output  for  80  or  32  columns. 

Examples: 

•  Because  PROCS  automatically  adjusts  for  either  32-  or  80- 
column  displays,  the  following  command  can  produce  either 
format: 


procs     e  |  ENTER  | 
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Fbllowing  is  a  possible  32-column  display  of  PROCS: 


Id      PId 

Uaer#      Pty 

Age      Sta 

Sigl 

Mem 

StPtr 

Primary 

2 

1 

0 

1  28 

128    $8Z 

0 

3 

$78E2 

Shell 

3 

G 

0 

128 

128    $80 

0 

1S 

$74B2 

Baslc09 

4 

2 

0 

128 

128    $80 

0 

6 

IGSF3 

Procs 

5 

0 

0 

128 

128   $80 

e 

3 

$6FB2 

Shell 

G 

0 

0 

128 

129   $80 

0 

3 

$68E2 

Shell 

Jbllowing  is  a  possible  80-column  display  of  PROCS: 

User  Mem  Stael 

Id    PId  Number    Pty  Age  Sti  Signl  Siz    Ptr      Primary  Module 


2    i 

i 

126  128  $88 

a 

3  J78B2  Shell 

3     6 

i 

128  128  m 

I 

16  «?4B2  Basic89 

4      5 

I 

128  128  m 

1 

3  J72E2  Shell 

5     I 

1 

128  129  188 

I 

3  J6FB2  Shell 

8     I 

I 

128  129  188 

i 

3  166E2  Shell 

7      4 

1 

128  128  188 

e 

6  1I5F3  Procj 
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PWD 
PXD 


Syntax:      pwd 
pxd 


Function:  PWD  shows  the  path  from  the  ROOT  directory  to 
the  current  data  directory.  PXD  shows  the  path  from  the 
ROOT  directory  to  the  current  execution  directory. 


Notes: 


OS-9  keeps  a  current  data  directory  and  current  execution 
directory  for  each  process.  Use  PWD  and  PXD  to  show 
where  your  current  data  and  execution  directories  are 
located  on  the  disk  or  disks  you  are  using. 


Examples: 


The  following  example  uses  a  full  pathlist.  CHD  changes 
the  current  data  directory  to  the  MANUALS  directory. 


chd    /d1  /steve/textf  i les/manuals  S ENTER  l 


To  display  the  full  path  to  the  data  directory,  type: 


pwd  J  ENTER  I 

The  screen  displays  the  data  directory  path: 

/D1 /STEVE/TEXTFILES/MANUALS 

•  The  following  commands  cause  the  current  data  directory 
to  move  up  one  level  in  the  directory  hierarchy  and  then 
display  the  data  directory. 


chd     .  .  I  ENTER  ] 


pwd  |  ENTER  | 

/D1/STEVE/TEXTFILES 
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•  The  following  commands  change  the  current  data  directory 

to  the  parent  directory  and  then  display  the  current  data 
-^  directory. 


chd     .  .  I  ENTER  I 


pwd  [  ENTER  | 

/D1 /STEVE 

The  following  command  displays  the  current  execution 
directory,  CMDS. 


pxd  |  ENTER  I 
/D0/CMDS 
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RENAME 

Syntax:      rename  pathlist  filename 

Function:  Gives  the  specified  file  or  directory  a  new  name. 

Parameters: 

pathlist  The  current  name  of  the  file  or  directory. 

filename.  The  new  name. 

Notes: 

•  You  must  have  write  permission  for  the  file. 

Examples: 

•  To  change  a  file's  name  from  Blue  to  Purple,  type: 


rename    blue    purple  [ ENTER  | 

To  rename  a  file  in  the  USER9  directory  of  Drive  /D3,  type: 


rename    /d3/user9/tes t    temp  |  ENTER  1 

In  the  following  example,  DIR  displays  the  names  of  the 
files  in  the  current  data  directory.  RENAME  changes  the 
filename  Animals  to  Mammals.  Another  DIR  command 
shows  that  RENAME  has  performed  properly. 


^V 


dir  (ENTER 


The  screen  displays: 

Directory  of  .  16:22:53 

myfile       animals 


rename  animals  mammals  I  ENTER  j 


dir  I  ENTER  I 
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The  screen  now  shows: 

Directory  of  .  16:23:22 

myfile      mammals 
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SETIME 


Syntax:      setime  [yy/mm/dd  hh:mm[:ss]] 


Function:  Sets  the  system  date  and  time,  and  activates  the 
real  time  clock. 


Parameters: 

yy 

mm 

dd 

hh 

mm 
ss 


The  year  in  a  two-digit  format  (86  for  1986). 

The  month  in  a  one  or  two-digit  format  (01  or 
1  for  January,  12  for  December), 

The  day  of  the  month  in  a  one-  or  two-digit 
format,  such  as  21. 

The  hour  in  a  one-  or  two-digit,  24-hour  for- 
mat (15  for  3  p.m.). 

Minutes  in  a  one-  or  two-digit  format,  such  as 

03,  5,  or  55. 

Seconds  in  a  one-  or  two-digit  format,  such  as 

04,  5,  or  25. 


Options: 

Specifying  seconds  in  the  new  time  entry  is  optional. 


Notes: 


You  can  include  the  date  and  time  parameters.  If  you  do 
not,  SETIME  asks  you  for  them. 

Numbers  are  one-  or  two-  decimal  digits  using  the  space, 
colon,  semicolon,  or  slash  as  delimiters. 

The  CC3go  module  starts  the  clock  on  system  startup,  so 
multitasking  is  possible  without  use  of  the  SETIME  utility. 
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If  you  do  not  set  the  date  and  time  when  booting  OS-9,  the 
system  cannot  accurately  update  the  "Last  modified"  date 
and  time  for  files. 


Examples: 


To  set  the  date  and  time  to  August  15,  1986,  3:45  p.m., 
type: 


setime    86,08,15,15,45  |  ENTER  | 

To  set  the  same  date  using  a  slightly  different  but  equally 
acceptable  format,  type: 


setime    8G/08/15    15/45/08  |  ENTER  | 
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SETPR 


Syntax:      setpr  procID  number 


Function:  Changes  the  CPU  priority  of  a  process.  The  priority 
of  a  process  determines  the  CPU  time  allotted  to  it  under 
multi-tasking  conditions. 


Parameters: 

procID  The  number  of  the  process  for  which  you  want 

to  change  the  priority. 

number  The  new  priority  number. 

Notes: 

•  The  process  priority  number  is  a  decimal  number  in  the 
range  1  (lowest  priority)  to  255.  If  you  need  information 
about  the  process  ID  number  and  current  priority,  use 
PROCS. 

•  "You  can  use  SETPR  only  on  processes  that  have  your  user 
number. 

•  SETPR  does  not  appear  in  the  CMDS  directory  because  it 
is  built  into  the  shell. 

•  A  Super  User  (User  0)  can  set  any  process  priorities. 

Examples: 

•  To  set  or  change  the  priority  of  Process  8  to  250,  type: 


setpr    8   252  |  ENTER  | 
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In  the  following  commands  PROCS  displays  process  ID 
numbers  and  other  information.  Then,  SETFR  sets  Process 
3  to  a  priority  of  128.  The  final  command  confirms  the 
change. 


procs  |  ENTER  1 

Following  is  a  sample  screen  display: 

User  Mem  Stack 

Id    PId  Number    Pty  Age  Sts  Slgnl  Siz    Ptr     Primary  Module: 


2 

1 

1 

1  SB  1 28  IB1 

i 

3  J78E2  Shell 

3 

6 

8 

1 28  128  m 

0 

16  $?4B2  Basic89 

4 

2 

8 

mm  m 

1 

6  $!5F3  Procs 

s 

1 

i 

mm  m 

8 

3  SGFB2  Shell 

6 

8 

I 

128  129  (88 

8 

3  J68E2  Shell 

sfitpr  3  2SS  |  ENTER  ] 
procs  I  ENTER  1 


Id    PId  Number 

Ply  Age  Sts  S 

ignl 

Slz    Ptr      Primary  Module 

2      1 

8 

128  128  $88 

8 

3  J78B2  Shell 

3     6 

8 

255  128  (88 

8 

1G  I74S2  Basic89 

4      5 

8 

128  128  188 

8 

3  I72E2  Shell 

S      8 

1 

128  129  188 

8 

3  (6FB2  Shell 

6      i 

1 

128  129  (88 

1 

3  I68E2  Shell 

7     4 

I 

128  128  $81 

1 

6  HSF3  Procs 
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SHELL 


Syntax:      shell  arglist 


Function:  The  shell  is  OS-9's  command  interpreter  program.  It 
reads  data  from  its  standard  input  path  (the  keyboard)  or 
redirected  data  from  a  file.  It  interprets  the  data  as  a 
sequence  of  commands.  The  function  of  the  shell  is  to  initiate 
and  control  execution  of  other  OS-9  programs. 

Parameters: 

arglist  The  commands,  parameters,  and  options  given 

SHELL  in  a  command  line. 


Notes: 


The  shell  reads  and  interprets  one  text  line  at  a  time  from 
the  standard  input  path  until  it  reaches  an  end-of-file 
marker.  At  that  time  it  terminates  itself. 

When  another  program  calls  the  shell,  a  special  case  occurs 
in  which  the  shell  takes  the  argument  list  as  its  first  line 
of  input.  If  this  command  line  consists  of  built-in  com- 
mands only,  the  shell  reads  and  processes  more  lines.  Oth- 
erwise, control  returns  to  the  calling  program  after  the 
shell  processes  the  single  command  line. 

When  operating  from  the  shell,  you  do  not  need  to  specify 
the  SHELL  command  to  execute  a  program,  a  command,  or 
a  built-in  shell  function.  Using  SHELL  before  a  command 
causes  the  existing  shell  to  fork  an  additional  shell,  which 
then  forks  the  specified  process,  such  as: 

shell    dire  I  ENTER  I 


Issuing  a  command  without  SHELL  causes  the  existing 
shell  to  fork  the  specified  process,  such  as: 


dir    e  I  ENTER  I 
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The  following  two  commands  also  have  identical  effects: 


shell    x  I  ENTER  I 


x  I  ENTER  | 
The  shell  command  separators  are: 

;  Sequential  execution  separator 

&  Concurrent  execution  separator 

!  Pipeline  separator 

|  enter  |    end-of-line  (sequential  execution  separator) 
The  Shell  command  modifiers  are: 

<  Redirect  standard  input 

>  Redirect  standard  output 

>>        Redirect  standard  error  output 

<>        Redirects  standard  input  to  standard  output 

<>>     Redirects  standard  input  to  standard  error 
output 

>»     Redirects  standard  output  to  standard  error 
output 

#ra        Set  the  process  memory  size  in  pages 

#nK      Set  the  program  memory  size  in  1  kilobyte  units. 

The  following  Shell  command  parameters  tell  OS-9  to: 

chd  pathlist  Change  the  data  directory 

kill  procID  Send  the  termination  signal  to 

process 

setpr  procID  Change  the  specified  process 

number  priority 

chx  pathlist  Change  the  execution  directory 

i  =  devicename  Create  an  immortal  process 

w  Wait  for  any  process  to  die 
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p  Turn  on  prompting 

-p  Turn  off  prompting 

t  Echo  input  lines  to  standard  output 

-t  Not  echo  input  lines 

-x  Not  terminate  on  an  error 

x  Terminate  on  error 

*  Not  process  the  following  text 

See  Chapter  3  for  more  information  on  the  operation  of  the 
shell. 
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TMODE 


Syntax:      tmode  [pathnum]  [paramtist]  [...] 

Function:  Displays  or  changes  the  initialization  parameters  of 
the  terminal.  TMODE  automatically  adjusts  its  output  for  32- 
or  80-column  displays. 

Common  uses  include  changing  baud  rates  and  control  key 
definitions. 


Parameters: 

pathnum 


paramlist 
Options: 

upc 

-upc 
bsb 

-bsb 

bsl 


One  of  the  standard  path  numbers: 

.0  =  standard  input  path 

.1  =  standard  output  path 

.2  =  standard  error  output  path 

One  of  the  following  options. 


Displays  uppercase  characters  only.  Lowercase 
characters  automatically  convert  to  uppercase. 

Displays  both  upper-  and  lowercase  characters. 

Causes  a  backspace  to  erase  characters.  Back- 
space characters  echo  as  a  backspace-space- 
backspace  sequence.  This  setting  is  the  system 
default. 

Causes  backspace  not  to  erase.  Only  a  single 
backspace  echoes. 

Enables  backspace  over  a  line.  Deletes  lines  by 
sending  backspace-space-backspace  sequences 
to  erase  a  line  (for  video  terminals).  This  set- 
ting is  the  system  default. 
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-bsl 

echo 

-echo 

If 


-If 

pause 


-pause 
null  =  n 


pag  =  n 

bsp  =  h 
bse  =  A 
del  =  fc 
bell  =  h 
eor  =  h 


Disables  backspace  over  a  line.  To  delete  a  line, 
TMODE  prints  a  new  line  sequence  (for  hard- 
copy  terminals). 

Input  characters  echo  on  the  terminal.  This 
setting  is  the  system  default. 

Turns  off  the  echo  default. 

Turns  on  the  auto  line  feed  function.  Line 
feeds  automatically  echo  to  the  terminal  on 
input  and  output  carriage  returns.  The  auto 
line  feed  setting  is  the  system  default. 

Turns  off  the  auto  line  feed  default. 

Turns  on  the  screen  pause.  This  setting  sus- 
pends output  when  the  screen  fills.  See  the 
pag  parameter  for  a  definition  of  screen  size. 
Resume  output  by  pressing  the  space  bar.  This 
setting  is  the  system  default. 

Turns  off  the  screen  pause  mode. 

Sets  the  null  count — the  number  of  null  ($00) 
characters  transmitted  after  carriage  returns 
for  the  return  delay.  The  value  n  is  in  decimal. 
The  default  is  0. 

Sets  the  length  of  the  video  display  page  to  n 
(decimal)  lines.  This  setting  affects  the  pause 
mode. 

Sets  the  backspace  character  for  input.  The 
value  h  is  in  hexadecimal.  The  default  is  08. 

Sets  the  backspace  character  for  output.  The 
value  h  is  in  hexadecimal.  The  default  is  08. 

Sets  the  delete  line  character  for  input.  The 
value  h  is  in  hexadecimal.  The  default  is  18. 

Sets  the  bell  (alert)  character  for  output.  The 
value  h  is  in  hexadecimal.  The  default  is  07. 

Sets  the  end-of-record  (carriage  return)  char- 
acter for  input.  This  setting  requires  a  value 
in  hexadecimal.  The  default  is  0D. 
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eof=/i  Sets  the  end-of-file  character  for  input.  The 

value  h  is  in  hexadecimal.  The  default  is  IB. 

type  =  h  For  external  devices,  use  type  for  ACIA  (asyn- 

chronous communications  interface  adapter) 
initialization  values  (hexadecimal).  The 
default  is  00.  Bits  5-7  set  either  MARK, 
SPACE,  or  no  parity  on  all  devices.  Codes  for 
these  are: 

000  =  no  parity 

101  =  MARK  parity  transmitted,  no 
checking 

111  =  SPACE  parity  transmitted,  no 
checking 

Oil  =  even  parity  (available  only  with 
the  external  ACIA  pak  and  Mod- 
pak  devices) 

001  =    odd  parity  (available  only  with 

the  external  ACIA  pak  and  Mod- 
pak  devices) 

Bit  4  selects  auto-answer  modem  support  fea- 
tures. 

1  =  on 

0  =  off 

See  "Technical  Information  for  the  RS232 

Port"  in  Chapter  5  for  more  information. 

R>r  TERM-VDG,  the  type  byte  has  a  different 
use: 

Bit  0  specifies  a  machine  with  true  low- 
ercase capability.  Set  Bit  0  to  turn  on 

true  lowercase. 

For  TERM- WIN,  use  a  value  of  80  to  specify  a 

window  device. 

reprint = h         Sets  the  reprint  line  character.  The  value  h  is 
in  hexadecimal. 
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dup=ft  Sets  the  character  to  duplicate  the  last  input 

line.  The  value  h  is  in  hexadecimal.  The 
default  is  01. 

psc  =  ft.  Sets  the  pause  character.  The  value  of  the 

character  is  in  hexadecimal.  The  default  is  17. 

abort = h  Sets  the  terminate  character  (normally  CON- 

TROL C).  The  value  of  the  character  is  in 
hexadecimal. 

quit = ft  Sets  the  quit  character  (normally  CONTROL 

E).    The    value    of  the    character    is    in 
hexadecimal. 

baud  =  ft  Sets  the  baud  rate,  word  length,  and  stop  bits 

for  a  software-controllable  interface.  The  codes 
for  the  baud  rate  are: 

0  =  110     3=1200     6=  9600 

1  =  300     4  =  2400     7  =  19200  (ACIAPAK  only) 

2  =  600     5  =  4800     7  =  32000  (SIO  only) 

Bits  0-3  determine  the  baud  rate. 
Bit  4  is  reserved  for  future  use. 
Bits  5-6  determine  the  word  length; 

00  =  8  bits 

01  =  7  bits 

Bit  7  determines  the  number  of  stop  bits: 

0  =  1  stop  bit 

1  =  2  stop  bits 

See  "Technical  Information  for  the  RS232 
Port"  in  Chapter  5  for  further  information. 
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Notes: 

•  You  can  specify  any  number  of  parameters  from  the  options 
list,  separating  them  by  spaces  or  commas.  If  you  don't 
specify  parameters,  TMODE  displays  the  current  values  of 
the  available  options. 

•  You  can  use  a  period  and  a  number  to  specify  the  pathnum- 
ber  on  which  to  read  or  set  options.  If  you  don't  specify  a 
path,  TMODE  affects  the  standard  input  path. 

•  TMODE  works  only  if  a  path  to  the  file/device  is  open.  Use 
XMODE  to  alter  device  descriptors  and  set  device  initial 
operating  parameters. 

•  TMODE  can  also  alter  the  baud  rate,  word  length,  stop 
bits,  and  parity  for  devices  already  initialized. 

•  If  you  use  TMODE  in  a  procedure  file,  you  must  specify  one 
of  the  standard  output  paths  (.1  or  .2).  This  procedure  is 
necessary,  because  the  command  redirects  the  SHELL'S 
standard  input  path  to  come  from  a  disk  file.  (You  can  use 
TMODE  only  on  SCFMAN-type  devices.)  For  example,  to 
set  lines  per  page  for  standard  output,  use  this  line: 


TMODE     .1    pag=24  |  ENTER  | 

Examples: 

•  The  following  command  line  sets  the  terminal  to  display 
upper-  and  lowercase,  sets  the  null  count  to  4,  and  turns  on 
the  screen  pause  function. 


tmode    -upc    If    Tiull-t    pause  I  ENTER  | 

The  next  command  sets  the  screen  page  length  (number  of 
lines)  to  24,  turns  on  the  screen  pause  function  and  the 
backspace-over-line  function,  and  sets  the  backspace  charac- 
ter value  to  8. 


tmode    pag  =  24    pause    bsl    -echo    bsp-8  [ENTER  ] 
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TUNEPORT 


Syntax:      tuneport  [device]  [-s  =  value] 


Function:  Lets  you  test  and  set  delay  loop  values  for  the  cur- 
rent baud  rate  and  select  the  best  value  for  your  printer  or 
terminal. 


Parameters: 

device  The  device  you  want  to  test,  either  your 

printer  (/p)  or  terminal  (/tl). 

value  A  new  delay  loop  value. 

Options: 

-s=  Sets  a  new  delay  loop  value, 

Examples: 

•  The  following  command  provides  a  test  operation  for  your 
printer. 


tuneport    /p  |  ENTER  | 

After  a  short  delay,  TUNEPORT  displays  the  current  baud 
rate  and  sends  data  to  the  printer  to  see  if  it  is  working 
properly.  The  program  then  displays  the  current  delay  value 
and  asks  for  a  new  value.  Enter  a  decimal  delay  value  and 
press  |  enter  |.  Again,  TUNEPORT  sends  data  to  the  printer 
as  a  test.  Continue  this  process  until  you  find  the  best 
value.  When  you  are  satisfied,  press  |  enter  |  instead  of  enter- 
ing a  value  at  the  prompt.  A  closing  message  displays  your 
new  value. 

Use  the  same  process  to  set  a  new  delay  loop  value  for  the 
/Tl  terminal. 
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The  following  command  line  sets  the  delay  bop  value  for 
your  printer  to  255. 


tuneport    /p    -  a  ■  2  2  5  [ENTER] 

Use  such  a  command  on  future  system  boots  to  set  the  opti- 
mum delay  value  determined  with  the  TUNEPORT  test 
function.  Then,  using  OS9GEN  or  COBBLER,  generate  a 
new  boot  file  for  your  system  diskette,  "Vbu  can  also  use  the 
■s  option  with  TUNEPORT  in  your  system  Startup  file  to 
set  the  value. 
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UNLINK 


Syntax:      unlink  modname  [...] 


Function:  Tells  OS-9  that  the  named  memory  module(s)  is  no 
longer  needed  by  the  user. 


Parameters: 

modname  One  or  more  modules  you  want  to  unlink. 

Options: 

In  one  command  line,  you  can  specify  as  many  modules  as  you 
want  to  unlink. 


Notes: 


Whether  OS-9  destroys  the  modules  and  reassigns  their 
memory  depends  on  whether  the  module  is  in  use  by  other 
processes.  Each  process  using  a  module  increases  its  link- 
count  by  one.  Each  UNLINK  you  issue  decreases  its  link- 
count  by  1.  When  the  link-count  reaches  0,  OS-9  deallo- 
cates the  module. 

You  should  unlink  modules  whenever  possible  to  make  most 
efficient  use  of  available  memory  resources.  Modules  you 
have  loaded  and  linked  might  need  to  be  unlinked  twice  to 
remove  them  from  memory. 
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Warning:  Never  attempt  to  unlink  a  module  you  didn't  load 
or  link,  and  never  unlink  a  module  that  is  in  use  by  pro- 
grams (displayed  by  the  PROCS  command). 


Examples: 


To  unlink  three  modules  named  Pgml,  Pgm5,  and  Pgm99, 
type: 


unlink    pgml    pgmS   pgm99  |  ENTER  | 

In  the  following  eommand  sequence,  MDIR  first  displays 
the  modules  in  memory.  The  next  command  unlinks  the 
edit  module.  The  output  of  the  final  command  (MDIR) 
shows  that  UNLINK  is  successful — Edit  no  longer  appears 
on  the  list. 


mdlr  (ENTER 


A  possible  screen  display  is: 

Module  Directory  at  88:01:08 
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The  new  screen  display  is: 

Module  Directory  at  98:83:15 
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WCREATE 


Syntax:      wcreate  /wpath  -s  =  type  xpos  ypos  xsize 
ysize  foreground  background  [border] 

Function:  Initializes  and  creates  a  window. 


Parameters: 

/wpath  The  window  device  name  of  the  window  you 

are  creating  (W,  Wl,  W2,  W3,  and  so  on). 

xpos  The  x  co-ordinate  (in  decimal}  for  the  starting 

position  of  the  upper  left  corner  of  the  screen. 

ypos  The  y  co-ordinate  (in  decimal)  for  the  starting 

position  of  the  upper  left  corner  of  the  screen. 

xsize  The  horizontal  size  of  the  screen  in  columns, 

in  the  range  1  to  80  (in  decimal). 

ysize  The  vertical  size  of  the  screen  in  lines,  in  the 

range  1  to  24  (in  decimal). 

foreground        The  window  foreground  color. 

background       The  window  background  color. 

border  An  optional  window  border  color.  The  default 

is  black. 


Options: 

-s  =  type 


The  screen  type,  chosen  from  the  following 
list: 

Type  Description 

1  =  40-column  hardware  text  screen 

2  =  80-coiumn  hardware  text  screen 
J  X=  640  x  192  two-color  screen 

$  X  =  320  x  192  four-color  screen 

y  %  =  640  x  192  four-color  screen 

0  X  =  320  x  192  sixteen-color  screen 
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If  you  use  the  -s  =  type  option,  you  must  spec- 
ify a  border  color  in  the  command  line, 

-z  Directs  WCREATE  to  accept  input  from  the 

standard  input  (redirected  from  a  file), 

-?  Produces  a  help  message  for  the  command. 

Examples: 

•  To  create  a  full  screen,  80-column  text  window  on  /wl, 
type: 


wcreate    /w1     -5  =  2    0    0    80    24    7    4    1  (ENTER] 


To  create  two  windows  (/w2  and  /w3)  on  a  640  x  192  graph- 
ics screen  in  which  /w2  is  the  upper  left  of  the  display  and 
/w3  is  the  right  half  of  the  display,  first  use  build  to  create 
an  input  file: 


build   wf  lie  |  ENTEfl  I 


?    /w2    -5  =  0?    0    0    40     12    7    4    1  [  ENTER  I 


?    /w3   40    0    40    24    4    7  I  ENTER  I 


?  I  ENTER  I 


Then,  create  the  windows  using  Wfile  as  input: 


wcreate    -z     <    wfile  I  ENTER  I 
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\ou  can  use  the  -z  option  to  create  windows  in  your  system 
startup  file.  For  example,  the  following  startup  file  sets  up 
several  windows,  along  with  the  usual  SETIME. 

t 

*  lock  the  shell  in  memory  and  set  the  time 

*  link  shell 
setlme  <  /1 

*  create  the  new  windows 
wcreate  -z 

*  set  up  an  80-column  full  window  for  /w1 
/w1  -s=a  0  0  88  24  7  4  1 

«  set  up  a  40  column  full  window  for  /w2 

/w2  -s-1  0  0  40  24  7  4  1 

*  set  up  /w3  and  /w4  as  halves  of  a 
•640  x  192  display 

/w3  -s+7  0  0  40  24  7  4  1 
/w4  40  0  40  24  4  7 

*  the  following  blank  line  terminates  input 

*  from  wcreate 

«  get  the  graphics  fonts  loaded 
merge  sys/stdfonts  >  /w1 

Now,  when  the  system  boots,  it  has  four  windows  defined, 
besides  TERM.  As  shown,  you  can  use  an  asterisk  as  the 
first  character  on  a  line  in  order  to  allow  comments  in  the 
file. 
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XMODE 


Syntax:      xmode  devname  [paramlist] 

Function:  Displays  or  changes  the  initialization  parameters  of 
any  SCF-type  device  such  as  the  video  display,  printer, 
RS-232  port,  and  others.  XMODE  automatically  adjusts  its 
output  for  32-  or  80-column  displays. 

Common  uses  include  changing  baud  rates  and  control  key 
definitions. 


Parameters: 

pathnum 

paramlist 
Options: 
upc 

-upc 

bsb 

■bsb 
bsl 

-bsl 


The  device  name  to  change,  such  as  /term, 
/w7,  /t2,  and  so  on. 

One  of  the  following  options. 


Displays  uppercase  characters  only.  Lowercase 
characters  automatically  convert  to  uppercase. 

Displays  both  upper-  and  lowercase  characters. 

Causes  a  backspace  to  erase  characters.  Back- 
space characters  echo  as  a  backspace-space- 
backspace  sequence.  This  setting  is  the  system 
default. 

Causes  backspace  not  to  erase.  Only  a  single 
backspace  echoes. 

Enables  backspace  over  a  line.  Deletes  lines  by 
sending  backspace-space-backspace  sequences 
to  erase  a  line  (for  video  terminals).  This  set- 
ting is  the  system  default. 

Disables  backspace  over  a  line.  To  delete  a  line, 
you  must  print  a  new  line  sequence  (for  hard- 
copy  terminals). 
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echo 

-echo 
If 


-If 
pause 


-pause 
null=n 


pag  =  n 

bsp  =  /i 
bse=h 
del  =  A 
be\l  =  h 
eor  =  h 

eof=A 


Input  characters  echo  on  the  terminal.  This 
setting  is  the  system  default. 

Turns  off  the  echo  default. 

Turns  on  the  auto  line  feed  function.  Line 
feeds  automatically  echo  to  the  terminal  on 
input,  and  they  output  carriage  returns.  The 
auto  line  feed  setting  is  the  system  default. 

Turns  off  the  auto  line  feed  default. 

Turns  on  the  screen  pause.  This  setting  sus- 
pends output  when  the  screen  fills.  See  the 
pag  parameter  for  a  definition  of  screen  size. 
Resume  output  by  pressing  the  space  bar.  This 
setting  is  the  system  default. 

Turns  off  the  screen  pause  mode. 

Sets  the  null  count — the  number  of  null  ($00) 
characters  transmitted  after  carriage  returns 
for  the  return  delay.  The  value  n  is  in  decimal. 
The  default  is  0. 

Sets  the  length  of  the  video  display  page  to  n 
(decimal)  lines.  This  setting  affects  the  pause 
mode. 

Sets  the  backspace  character  for  input.  The 
value  h  is  in  hexadecimal.  The  default  is  08. 

Sets  the  backspace  character  for  output.  The 
value  k  is  in  hexadecimal.  The  default  is  08. 

Sets  the  delete  line  character  for  input.  The 
value  h  is  in  hexadecimal.  The  default  is  18. 

Sets  the  bell  (alert)  character  for  output.  The 
value  h  is  in  hexadecimal.  The  default  is  07. 

Sets  the  end-of-record  (carriage  return)  char- 
acter for  input.  This  setting  requires  a  value 
in  hexadecimal.  The  default  is  0D. 

Sets  the  end-of-file  character  for  input.  The 
value  h  is  in  hexadecimal.  The  default  is  IB. 
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type  =  h  For  external  devices,  use  type  for  ACIA  (asyn- 

chronous communications  interface  adapter) 
initialization  values  (hexadecimal).  The 
default  is  00.  Bits  5-7  set  either  MARK, 
SPACE,  or  no  parity  on  all  devices.  Codes  for 
these  are: 

000  =    no  parity 

101  =  MARK  parity  transmitted,  no 
checking 

111  =   SPACE  parity  transmitted,  no 

checking 

Oil  =  even  parity  (available  only  with 
the  external  ACIA  pak  and  Mod- 
pak  devices) 

001  =  odd  parity  (available  only  with 

the  external  ACIA  pak  and  Mod- 
pak  devices) 

Bit  4  selects  auto-answer  modem  support  fea- 
tures. 

1  =  on 

0  =  off 

See  "Technical  Information  for  the  RS232 
Port"  in  Chapter  5  for  more  information. 

For  TERM-VDG,  the  type  byte  has  a  different 
use: 

Bit  0  specifies  a  machine  with  true  low- 
ercase capability.  Set  Bit  0  to  turn  on 
true  lowercase. 

For  TERM-WIN,  use  a  value  of  80  to  specify  a 

window  device. 

reprint  =  h         Sets  the  reprint  line  character.  The  value  h  is 
in  hexadecimal. 

dup  =  &  Sets  the  character  to  duplicate  the  last  input 

line.  The  value  h  is  in  hexadecimal.  The 
default  is  01. 
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psc  =  fc  Sets  the  pause  character.  The  value  of  the 

character  is  in  hexadecimal.  The  default  is  17. 

abort  =  fe  Sets  the  terminate  character  (normally  CON- 

TROL C).  The  value  of  the  character  is  in 
hexadecimal. 

quit = h  Sets  the  quit  character  (normally  CONTROL 

E).    The    value    of  the    character    is    in 
hexadecimal. 

baud  =  h  Sets  the  baud  rate,  word  length,  and  stop  bits 

for  a  software-controllable  inter  face.  The  codes 
for  the  baud  rate  are: 

0  =  110     3  =  1200     6=  9600 

1  =  300    4  =  2400     7  =  19200  ( ACIAPAK  only) 
3  =  600     5  =  4800     7  =  32000  (SIO  only) 

Bits  0-3  determine  the  baud  rate 
Bit  4  is  reserved  for  future  use 
Bits  5-6  determine  the  word  length: 

00  =  8  bits 

01  =  7  bits 

Bit  7  determines  the  number  of  stop  bits: 

0  =  1  stop  bit 

1  =  2  stop  bits. 

See  "Technical  Information  for  the  RS232 
Port"  in  Chapter  5  for  further  information. 


Notes: 


XMODE  is  similar  to  TMODE,  but  there  are  differences. 
TMODE  operates  only  on  open  paths,  so  its  effect  is  tempo- 
rary. XMODE  updates  the  device  descriptor.  Its  change  per- 
sists as  long  as  the  computer  is  running,  even  if  you  or  the 
system  repeatedly  open  and  close  the  paths  to  the  device. 

If  you  use  XMODE  to  change  parameters  and  the  COB- 
BLER program  to  make  a  new  system  diskette  or  to  re- 
make the  boot  tracks  on  the  current  system  diskette,  the 
process  permanently  changes  the  parameters  on  the  new 
system  diskette. 
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XMODE  requires  that  you  specify  a  device  name.  If  you  do 
not  specify  parameters,  XMODE  displays  the  present  value 
for  each  parameter.  %u  can  use  any  number  of  parameters, 
separating  them  with  spaces  or  commas. 


Examples: 


The  following  command  sets  the  term  (video)  for  upper-  and 
lowercase,  the  null  count  to  4,  the  backspace  character 
value  to  IF  hexadecimal,  and  turns  on  the  screen  pause 
function. 


xmode    /term    -upc    If    bse  =  1F    pause  [ENTER  | 
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Overview 

The  OS-9  Macro  Text  Editor  is  a  powerful,  easy-to-learn  text- 
preparation  system.  Use  it  to  prepare  text  for  letters  and  docu- 
ments or  text  to  be  used  by  other  OS-9  programs,  such  as  the 
assembler  and  high-level  languages.  The  text  editor  includes  the 
following  features: 

•  Compact  size 

•  Capability  of  having  multiple  read  and  write  files  open 
at  the  same  time 

•  All  OS-9  commands  usable  inside  the  text  editor 

•  Adjustable  workspace  size 

•  Repeatable  command  sequences 

•  Edit  macros  (special  utility  functions) 

•  Multiple  text  buffers 

•  Powerful  commands 

The  Macro  Text  Editor  is  about  5  kilobytes  in  size  and  requires 
at  least  2K  bytes  of  free  RAM  to  run. 

Text  Buffers 

As  you  enter  text,  the  editor  places  it  in  a  temporary  storage 
area  called  a  text  buffer.  A  text  buffer  acts  as  a  scratch  pad  for 
saving  text  that  you  can  manipulate  with  various  edit  com- 
mands. The  Macro  Text  Editor  can  use  multiple  text  buffers,  one 
at  a  time. 

A  buffer  in  use  is  called  the  edit  buffer.  Edit  also  has  another 
default  buffer  called  the  secondary  buffer.  As  well,  you  can  create 
additional  buffers  up  to  the  capacity  of  your  computer's  memory. 

Edit  Pointers 

The  Macro  Text  Editor  has  an  edit  pointer  that  identifies  your 
position  in  the  buffer,  in  a  manner  similar  to  holding  your  place 
in  a  book  with  your  finger. 
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The  pointer  is  invisible  to  you,  but  Edit  commands  can  reposi- 
tion it  and  display  the  text  to  which  it  points.  Each  buffer  has  its 
own  edit  pointer,  and  you  can  move  from  buffer  to  buffer  without 
losing  your  place  in  any  of  them. 

Entering  Commands 

The  Macro  Text  Editor  is  interactive.  This  means  you  and  the 
editor  carry  on  a  two-way  conversation.  You  issue  a  command, 
and  the  editor  carries  out  the  command  and  displays  the  result. 
When  you  are  through  making  changes,  you  can  save  your 
edited  file,  then  press  (T)  I  enter  |  to  quit  editing. 

When  the  editor  displays  E :  on  the  screen,  it  is  waiting  for  you 
to  type  a  command.  You  type  a  line  that  includes  one  or  more 
commands,  then  press  |  enter  |.  Edit  carries  out  the  commands  and 
again  displays  E : . 

If  you  enter  more  than  one  command  on  a  line,  separate  the 
commands  with  a  space.  If,  however,  a  space  is  the  first  charac- 
ter on  a  line,  the  editor  considers  the  space  to  be  an  insert  com- 
mand and  not  a  separator. 

Correct  a  typing  error  by  backspacing  over  it  or  by  deleting  the 
entire  line.  Note,  you  cannot  correct  a  line  after  pressing  [  enter  |. 


Control  Keys 

You  can  use  the  same  special  control  keys  with  Edit  that  you 
use  with  OS-9.  See  Appendix  D  for  a  complete  listing  of  these 
keys.  Following  is  a  list  of  some  of  the  control  keys  that  are  espe- 
cially useful  with  Edit: 

Control  Key(s)         Function 

Repeats  the  previous  input  line. 

Terminates  the  editor  and  returns  to  com- 
mand entry  mode. 

Displays  the  current  input  on  the  next  line. 

Backspaces    and    erases    the    previous 
character. 
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1  CTRL  |  |  A  | 

1  CTRL  |  LPJ 

1  CTRL  |  QQ 

1  CTRL | [H) 
orQ 
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Control  Key(s)         Function 


QT)  I  enter  |  Interrupts  the  editor  and  returns  to  com- 

mand entry  mode. 


1  ctrl  I  fwl  Temporarily  halts  the  data  output  to  your 

terminal  so  that  you  can  read  the  screen 
before  the  data  scrolls  off.  Output  resumes 
when  you  press  any  other  key. 


I  ctrl  |  (T)  or  Deletes  the  line. 

fSHiFfl  w 

I  Ctrl  1 1  break  1  Terminates  the  editor,  and  returns  to  com- 

mand entry  mode. 

Command  Parameters 

There  are  two  types  of  edit  parameters,  "numeric"  and  "string." 

Numeric  Parameters.  Numeric  parameters  specify  an  amount, 
such  as  the  number  of  times  to  repeat  a  command  or  the  number 
of  lines  affected  by  a  command.  If  you  do  not  specify  a  numeric 
parameter,  the  editor  uses  the  default  value  of  one.  Specify  all 
other  numeric  parameters  in  one  of  the  following  ways. 

•  Enter  a  positive  decimal  integer  in  the  range  0  to 
65,535.  For  example: 

0 

10 

5250 

65532 

31 

•  Enter  an  asterisk  (*)  as  a  shorthand  for  all  (all  the  way 
to  the  beginning,  all  the  way  to  the  end,  all  of  the  lines, 
and  so  on).  To  the  editor,  an  asterisk  means  infinity.  Use 
the  asterisk  to  specify  all  remaining  lines,  all  charac- 
ters, or  repeat  forever. 

•  Use  a  numeric  variable.  (See  "Parameter  Passing"  later 
in  this  chapter.) 
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String  Parameters.  String  parameters  specify  a  single  charac- 
ter, group  of  characters,  word,  or  phrase.  Specify  string  parame- 
ters in  either  of  the  following  ways. 

•  Enclose  the  group  of  characters  with  delimiters  (two 
matching  characters).  You  can  use  any  characters,  but 
they  must  match.  If  one  string  immediately  follows 
another,  separate  the  two  with  a  single  delimiter  that 
matches  the  others.  For  example: 

"string  of  characters" 

/STRING/ 

:  my  name  is  Larry  : 

"first  s t r i ng"second  string" 

/string  1/  string  2/ 

•  Use  a  string  variable.  (See  "Using  Macros"  later  in  this 
chapter.) 

Syntax  Notation 

Syntax  descriptions  indicate  what  to  enter  and  the  order  in 
which  to  do  it.  The  command  name  is  first;  type  it  exactly  as 
shown.  Follow  the  command  name  with  the  correct  parameters. 
Enter  eaeh  as  it  is  described  in  the  section  on  parameters. 

The  syntax  descriptions  for  each  command  use  the  following 
notations: 

n  =  numeric  parameter 

str  =  string  parameter 

C  =  space  character.  When  you  see  D,  press  the  space  bar. 

text  =  one  or  more  characters  terminated  by  pressing 

I  ENTER  I 


Getting  Started 

From  the  OS-9  prompt,  start  Edit  by  typing: 


edit  |  ENTER  | 

Enter  a  command  when  the  screen  shows  E : . 

You  can  quit  Edit  at  any  time  by  pressing  (T)  I  enter  |.  The  Q  com- 
mand terminates  the  editor  and  returns  you  to  the  OS-9  Shell, 
which  responds  with  the  OS -9 :  prompt. 
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Following  is  a  list  of  ways  you  can  start  the  editor,  including  the 
effect  of  each.  The  examples  call  a  file  that  already  exists  oldfik. 
They  call  a  file  to  be  created  newfile. 

EDIT  OS-9  loads  the  editor  and  starts  it.  The  com- 

mand does  not  establish  an  initial  read  or 
write  files,  but  you  can  perform  text  file  opera- 
tions by  opening  files  after  the  editor  is 

started. 

EDIT  newfile  OS-9  loads  the  editor  and  starts  it,  creating 
the  file  called  newfile.  Newfile  is  the  initial 

write  file.  There  is  no  initial  read  file.  How- 
ever, you  can  open  files  to  read  later. 

EDIT  oldffle  OS-9  loads  the  editor  and  starts  it.  The  initial 
read  file  is  oldfik.  The  editor  creates  a  file 
called  SCRATCH  as  the  initial  write  file. 
When  you  end  the  edit  session,  OS-9  deletes 
oldfik  and  renames  SCRATCH  to  oldfik.  This 
gives  the  appearance  of  oldfik  being  updated. 

Note:  The  two  OS-9  utilities  DEL  and 

RENAME  must  be  present  on  your  system  if 
you  wish  to  to  start  the  editor  in  this  manner. 

EDIT  oldfile        OS-9  loads  the  editor  and  starts  it.  The  initial 

newfile  read  file  is  oldfik.  The  editor  creates  newfik — 

the  initial  write  file.  The  terms  oldfik  and 

newfik  refer  to  any  properly  constructed  OS-9 
pathlist. 
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Edit  Commands 


Displaying  Text 

Ln  Lists  (displays)  the  next  n  lines,  starting  at 

the  current  position  of  the  edit  pointer.  The 
edit  pointer  position  does  not  change. 

l  1  enter  | 

displays  the  current  line.  If  the  edit  pointer  is 
not  at  the  beginning  of  the  line,  only  the  por- 
tion of  the  line  to  the  right  of  the  edit  pointer 
shows  on  the  screen. 


Xn 


13  [  ENTER  1 


displays  the  current  line  and  the  next  two 
lines. 


1*  I  enter  j 


displays  all  text  from  the  current  position  of 
the  edit  pointer  to  the  end  of  the  buffer. 

The  L  command  displays  text  regardless  of 
which  verify  mode  is  in  effect. 

Displays  the  n  lines  that  precede  the  edit 
pointer.  The  position  of  the  edit  pointer  does 
not  change.  For  example: 

x  I  enter  I 


displays  any  text  on  the  current  line  that  pre- 
cedes the  edit  pointer.  If  the  edit  pointer  is  at 
the  beginning  of  the  line,  the  command  dis- 
plays nothing. 


x3  [  ENTER  1 


displays  the  two  preceding  lines  and  any  text 
on  the  current  line  that  precedes  the  edit 
pointer. 

The  X  command  displays  text  regardless  of 
which  verify  mode  is  in  effect. 
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Manipulating  the  Edit  Pointer 


I  ctrl  |  (7)  or  (±)  Moves  the  edit  pointer  to  the  beginning  (first 
on  an  external  character)  of  the  text  buffer.  The  screen  shows 
terminal  the  up  arrow  when  you  hold  down  |  ctrl  |  and 

press  (T).  For  example, 

[  CTRL  |  (T|  |  ENTER  | 

moves  the  edit  pointer  to  the  beginning  of  the 
buffer. 

/  Moves  the  edit  pointer  to  the  end  (last  charac- 

ter) of  the  buffer.  For  example, 


ENTER 


/  1  ENTER  | 

moves  the  edit  pointer  past  the  end  of  the 
buffer. 

Moves  the  edit  pointer  to  the  beginning  of  the 
next  line  and  displays  it.  Use  this  command  to 
go  through  text  one  line  at  a  time.  You  can 
look  at  each  line,  correct  any  mistakes,  and 
then  move  to  the  next  line. 
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+ n  Moves  the  edit  pointer  either  to  the  end  of  the 

line  or  forward  n  lines  and  displays  the  line. 
Entering  a  value  of  zero  moves  the  edit  pointer 
to  the  end  of  the  current  line.  For  example: 
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Entering  a  value  other  than  zero  moves  the 
pointer  forward  n  lines  and  displays  the  line. 
For  example, 


ENTER 


moves  the  pointer  to  the  next  line  and  displays 
the  line.  This  command  performs  the  same 
function  as  I  enter  I. 


+  1  ^  f  enter! 


moves  the  pointer  ahead  10  lines  and  displays 
the  line. 


+  *     ENTER 


moves  the  edit  pointer  to  the  end  of  the  buffer. 

-n  Moves  the  edit  pointer  either  to  the  beginning 

of  the  line  or  backward  n  lines.  For  example: 


-0  I  ENTER  I 


moves  the  edit  pointer  to  the  beginning  of  the 
line  and  displays  the  line.  Entering  a  value 
other  than  zero  moves  the  edit  pointer  back  n 
lines.  For  example, 


-    enter 


moves  the  edit  pointer  back  one  line  and  dis- 
plays the  line. 


-5  I  ENTER  1 


moves  the  edit  pointer  back  five  lines  and  dis- 
plays the  line. 


-*  | ENTER | 

moves  the  edit  pointer  to  the  beginning  (top) 
of  the  buffer  and  displays  the  first  line. 
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>«  Moves  the  edit  pointer  to  the  right  n  charac- 

ters. Use  this  command  to  move  the  edit 
pointer  to  some  position  in  the  line  other  than 
the  first  character.  For  example, 


>     ENTER 


moves  the  edit  pointer  to  the  right  one 
character. 


>25  I  ENTER  I 


moves  the  edit  pointer  to  the  right  25 
characters. 


>  *     ENTER 


moves  the  edit  pointer  to  the  end  of  the  buffer. 

<n  Moves  the  edit  pointer  to  the  left  n  characters. 

Use  this  command  to  move  the  edit  pointer  to 
some  position  in  a  line  other  than  the  first 
character.  For  example: 


<    ENTER 


moves  the  edit  pointer  to  the  left  one 
character. 


<1  0  (ENTER  I 


moves    the    edit   pointer   to   the   left    10 
characters. 


<*  |  ENTER  | 

moves  the  edit  pointer  to  the  beginning  of  the 
buffer. 
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Inserting  and  Deleting  Lines 

ttext  Preceding  text  lines  with  a  space  inserts  the 

text  as  a  new  line  ahead  of  the  edit  pointer. 
The  position  of  the  edit  pointer  does  not 
change.  For  example, 


Jlnsert    this    line  |  ENTER] 
inserts  the  line. 


GLi  ne 

Xlne 

one 
two 
thr 

I  ENTER  ) 
[  ENTER  ] 

ULine 

ee  |  ENTER  | 

inserts  three  lines. 

In  sir  Inserts  a  line  of  n  copies  of  the  specified  string 

immediately  before  the  position  of  the  edit 
pointer.  The  position  of  the  edit  pointer  does 
not  change.  For  example, 


i40/»/  |  ENTER 


inserts  a  line  containing  40  asterisks.  You  can 
also  use  the  "I"  command  to  insert  a  line  con- 
taining a  single  copy  of  the  string.  This  func- 
tion is  important  when  you  want  to  use  a 
macro  to  insert  lines,  since  the  space  bar  can- 
not be  used  within  a  macro.  For  example, 


i"Line    to    insert"  |  ENTER] 
inserts  the  line. 
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Du  Deletes  (removes)  n  lines  from  the  edit  buffer, 

starting  with  the  current  line.  This  command 
displays  the  lines  to  be  deleted.  For  example: 


d  I  ENTER  I 


deletes  the  current  line,  regardless  of  the  posi- 
tion of  the  edit  pointer,  and  displays  it. 


d4  l  enter  I 


deletes  the  current  line  and  the  next  three 
lines, 


d*  I  ENTER  l 


deletes  everything  from  the  current  line  to  the 
end  of  the  buffer. 

Kn  Kills  (deletes)  n  characters,  starting  at  the 

current  position  of  the  edit  pointer.  This  com- 
mand displays  all  deleted  characters.  For 
example, 


k     ENTER 


deletes  the  character  at  the  edit  pointer. 


k4  |  ENTER  | 

deletes  the  character  at  the  current  position  of 
the  edit  pointer  and  the  next  three  characters. 


k*  [ENTER  I 


deletes  everything  from  the  current  position  of 
the  edit  pointer  to  the  end  of  the  buffer. 
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En  str  Extends  n  lines  by  adding  a  string  to  the  end 

of  each  line,  e  extends  a  line,  displays  it,  and 
then  moves  the  pointer  past  it.  For  example, 

e/this    is   a    comment/  |  ENTER  [ 

adds  the  string  "this  is  a  comment"  to  the  end 
of  the  current  line  and  moves  the  edit  pointer 
to  the  next  line. 


e3/xx  I  ENTER  I 


adds  the  string  xx  to  the  end  of  the  current 
line  and  the  next  two  lines.  It  moves  the 
pointer  past  these  lines. 

U  Unextends  (deletes)  the  remainder  of  a  line 

from  the  current  position  of  the  pointer.  Use  U 
to  remove  extensions,  such  as  comments,  from 
a  line.  For  example, 


u     ENTER 


deletes  all  the  characters  from  the  current 
position  of  the  pointer  up  to  the  end  of  the  cur- 
rent line. 

For  some  practice  in  using  the  commands  that  display  text, 
manipulate  the  edit  pointer,  and  insert  and  delete  lines,  turn  to 
Sample  Session  1  in  this  chapter. 
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Searching  and  Substituting 

Sn  string  Searches  for  the  next  n  occurrences  of  string. 

When  Edit  finds  an  occurrence,  it  displays  the 
line  and  moves  the  edit  pointer  past  it.  If  Edit 
does  not  find  the  string  or  if  all  the  occur- 
rences have  been  found,  the  edit  pointer  does 
not  move.  For  example, 

s/my    string/  [  ENTER  | 

searches  for  the  next  occurrence  of  "my 

string". 

s3"strung   out"  [ENTER! 

searches  for  the  next  three  occurrences  of 
"strung  out". 

s*/seek    and   find/  |  ENTER  | 

searches  for  all  occurrences  of  "seek  and  find" 
between  the  edit  pointer  and  the  end  of  the 
text. 

Cn  stringl  Changes  the  next  n  occurrences  of  stringl  to 

string2  string2.  When  Edit  finds  stringl,  it  moves  the 

edit  pointer  past  it  and  changes  stringl  to 
string2,  then  it  displays  the  updated  line.  If  it 
does  not  find  stringl  or  if  all  the  occurrences 
have  been  found,  the  edit  pointer  does  not 
move.  For  example, 

c/this/thnt/  I  ENTER  I 


changes  the  next  occurrence  of  "this"  to 
"that". 


c2/in/out/  I  ENTER 


changes  the  next  two  occurrences  of  "in"  to 
"out". 

c*!seek    and    f ind ! sought    and 
found!  |  ENTER  | 

changes  all  occurrences  of  "seek  and  find" 
that  are  between  the  edit  pointer  and  the  end 
of  text  to  "sought  and  found". 
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An  Sets  the  SEARCH/CHANGE  anchor  to  Col- 

umn n.  To  find  a  string  that  begins  in  a  spe- 
cific column,  set  the  anchor  to  the  column 
position  before  using  the  search  command  to 
find  it.  If  you  do  not  include  a  value  for  n,  Edit 
assumes  Column  1.  For  example: 


a  |  ENTER  1 

finds  a  string  only  if  it  begins  in  Column  1. 


a20  I  ENTER  1 


finds  a  string  only  if  it  begins  in  Column  20. 
If  you  use  the  A  command  to  set  the  anchor, 
this  setting  remains  in  effect  only  for  the  cur- 
rent command  line.  After  Edit  executes  the 
command,  the  anchor  automatically  returns  to 
its  normal  value  of  zero. 

For  some  practice  in  using  the  commands  that  search  and  substi- 
tute, turn  to  Sample  Session  2  in  this  chapter. 

Miscellaneous  Commands 

Td  Tabs  (moves)  the  edit  pointer  to  Column  n  of 

the  current  line.  If  n  exceeds  the  line  length, 
this  command  extends  the  line  with  spaces. 
For  example, 


t  I  enter  I 


moves  the  edit  pointer  to  Column  1  of  the  cur- 
rent line. 


t5  I  ENTER  I 


moves  the  edit  pointer  to  Column  5  of  the  cur- 
rent line. 
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.SHELL  Lets  you  use  any  OS-9  command  from  within 

command  the  editor.  The  remainder  of  the  command  line 

line  following  .SHELL  passes  to  the  OS-9  Shell  for 

execution.  For  example, 


.shell     dir    /d1  |  ENTER  | 

calls  the  OS-9  Shell  to  print  the  directory  Dl. 


.shell    bas tc09  |  ENTER  ] 
starts  BASIC09. 


.shell    edit    oldfile    newfl  le  [  ENTER  | 

restarts  the  editor. 

Mil  Adjusts  the  amount  of  memory  available  for 

buffers  and  macros.  If  the  workspace  is  full 
and  the  editor  does  not  allow  you  to  enter 
more  text,  increase  the  workspace  size.  If  you 
need  only  a  small  amount  of  the  available 
workspace,  decrease  the  workspace  size  so  that 
other  OS-9  programs  can  use  the  memory.  For 
example, 


m5000  I  ENTER  ] 


sets  the  workspace  size  to  5000  bytes. 


tn1  0000  I  ENTER  I 


sets  the  workspace  size  to  10000  bytes. 

Before  leaving  Edit,  you  can  increase  the 
workspace.  This  decreases  the  time  the  editor 
takes  to  copy  the  input  file  to  the  output  file, 
because  the  editor  can  read  and  write  more 
data  at  one  time.  Edit  changes  memory  in 
256-byte  pages.  For  the  M  command  to  have 
any  effect,  a  new  workspace  size  must  differ 
from  the  current  size  by  at  least  256  bytes. 
The  M  command  does  not  let  you  deallocate 
any  workspace  that  Edit  needs  for  buffers  or 
macros. 
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.SIZE 


Q 


Vmode 


Displays  the  size  of  the  workspace  and  the 
amount  that  has  been  used.  Pbr  example: 


.  size 
521 


15328 


521  is  the  amount  of  workspace  Edit  uses  for 
buffers  and  macros.  15328  is  the  amount  of 
available  memory. 

Ends  editing  and  returns  to  the  OS-9  Shell.  If 
you  specified  files  when  you  started,  Edit 
writes  the  text  in  Buffer  1  to  the  initial  write 
file  (specified  when  you  start  Edit).  Next  it 
copies  the  remainder  of  the  initial  input  file 
(specified  when  you  start  Edit)  to  the  initial 
write  file.  The  editor  then  terminates,  and 
control  returns  to  the  OS-9  Shell. 

Turns  the  verify  mode  on  or  off.  Edit  always 
starts  with  the  verify  mode  on.  Therefore,  the 
editor  displays  the  results  of  all  the  commands 
for  which  verify  is  appropriate.  If  you  do  not 
want  to  see  the  results  of  commands,  turn  off 
the  verify  mode  by  specifying  0  (zero)  for 
mode.  To  turn  verify  back  on,  specify  any  non- 
zero number.  For  example, 


v0  I  enter  I 


turns  off  the  verify  mode. 


v2  I  ENTER  I 


turns  on  the  verify  mode. 


v1  3  I  ENTER  ] 


turns  on  the  verify  mode. 

If  the  verify  mode  is  on  when  you  switch  to  a 
macro,  it  remains  on.  If  you  turn  off  verify 
while  in  the  macro,  it  is  restored  when  you 
return  to  the  editor. 
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Manipulating  Multiple  Buffers 

.DIR  Displays  the  directory  of  the  editor's  buffers 

and  macros.  For  example: 

BUFFERS: 

$  0  (secondary  buffer) 

«  1  (primary  buffer) 

S  (another  buffer) 

MACROS: 

MYMACRO 

LIST 

CGPY 

Bn  Makes  buffer  n  the  primary  buffer.  When  you 

switch  from  one  buffer  to  another,  the  old  one 
becomes  the  secondary  buffer,  and  the  new  one 
becomes  the  primary  buffer.  Sbr  example, 


hs  |  enter  | 

makes  Buffer  5  the  primary  buffer.  If  Buffer  5 
does  not  exist,  Edit  creates  it. 

Pa  Puts  (moves)  n  lines  into  the  secondary  buffer. 

This  command  removes  the  lines  from  the  pri- 
mary buffer,  starting  at  the  position  of  the 
edit  pointer,  and  inserts  them  into  the  second- 
ary buffer  before  the  current  position  of  the 
edit  pointer.  It  displays  the  text  that  is  moved. 
For  example, 


p  | enter  I 
moves  one  line  to  the  secondary  buffer. 


p5  |  enter  I 
moves  five  lines  to  the  secondary  buffer. 


ENTER 


moves  all  lines  that  are  between  the  current 
position  of  the  edit  pointer  and  the  end  of  text 
to  the  secondary  buffer. 
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Gn  Gets  (moves)  n  lines  from  the  secondary- 

buffer.  This  command  takes  the  lines  from  the 
top  of  the  secondary  buffer  and  inserts  them 
into  the  primary  buffer  before  the  current 
position  of  the  edit  pointer.  Edit  then  displays 
the  moved  lines.  When  used  with  the  P  com- 
mand, G  moves  text  from  one  place  to  another. 
For  example, 


ENTER 


gets  one  line  from  the  secondary  buffer. 


g5  |  ENTER  1 
gets  five  lines  from  the  secondary  buffer. 


ENTER 


gets  all  lines  from  the  secondary  buffer. 

For  some  practice  in  using  miscellaneous  commands  and  the 
commands  that  manipulate  multiple  buffers,  turn  to  Sample  Ses- 
sion 3  in  this  chapter. 

Text  File  Operations 

This  section  of  the  manual  describes  the  group  of  commands 
related  to  reading  and  writing  OS-9  text  files, 

.NEW  Gets  new  text.  Use  .NEW  when  editing  a  file 

that  is  too  large  to  fit  into  the  editor's  work- 
space. .NEW  writes  out  all  lines  that  precede 
the  current  line,  then  appends  an  equal 
amount  of  new  text  to  the  end  of  the  buffer. 

.NEW  always  writes  text  to  the  initial  output 
file  (created  when  you  start  the  editor)  and 
always  reads  text  from  the  initial  input  file 
(specified  when  you  start  the  editor). 

If  you  have  finished  editing  the  text  currently 
in  the  buffer,  you  can  "flush"  this  text  and  fill 
the  buffer  with  new  text  by  moving  the  edit 
pointer  to  the  bottom  of  the  buffer  and  then 
using  the  .NEW  command.  For  example: 


/.new  I  ENTER  I 
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If  you  wish  to  retain  part  of  the  text  that  is 
already  in  the  buffer,  move  the  edit  pointer  to 
the  first  line  you  wish  to  retain  and  then  type 
.new.  This  command  "flushes"  all  lines  that 
precede  the  edit  pointer.  It  then  tries  to  read 
in  new  text  that  is  the  same  size  as  the  por- 
tion flushed  out. 

.READ  str  Prepares  an  OS-9  text  file  for  reading,  str 

specifies  the  pathlist.  For  example. 


.read    "myf  ile"  |  ENTER] 

closes  the  current  input  file  and  opens 
"myfile"  for  reading. 

You  can  specify  an  empty  pathlist.  For 

example, 


.read    ""    ENTER 


closes  the  current  input  file  and  restores  the 
initial  input  file  (specified  when  you  start  the 
editor)  for  reading. 

An  open  file  remains  attached  to  the  primary 
buffer  until  you  close  the  file.  You  can  have 
more  than  one  input  file  open  at  any  time  by 
using  the  .READ  command  to  open  them  in 
different  buffers. 

To  read  these  files,  switch  to  the  proper  buffer, 
and  then  use  the  R  command  to  read  from 
that  buffer's  input  file.  To  close  a  file,  you 
must  be  in  the  same  buffer  where  the  file  was 
opened. 
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.WRITE  str  Opens  a  new  file  for  writing.  The  string  speci- 

fies the  pathlist  for  the  file  you  wish  to  create. 
For  example, 


.write    "newf  i  le"  I  ENTER  I 


closes  the  current  write  file  and  creates  one 
called  "newfile".  You  can  specify  an  empty 
pathlist.  For  example: 


.write    ""  I  ENTER  I 


closes  the  current  write  file  and  restores  the 
initial  write  file  (specified  when  you  start  the 
editor). 

.WRITE  attaches  a  new  write  file  to  the  pri- 
mary buffer  that  remains  attached  until  you 
close  the  file.  %u  can  have  more  than  one 
write  file  open  by  using  .WRITE  to  open  them 
in  different  buffers.  To  write  these  files,  switch 
to  the  proper  buffer.  To  close  a  file,  you  must 
be  in  the  same  buffer  where  the  file  was 
opened. 

Rfl  Reads  (gets)  n  lines  of  text  from  the  buffer's 

input  file.  It  displays  the  lines  and  inserts 
them  before  the  current  position  of  the  edit 
pointer.  For  example, 


r     ENTER 


reads  one  line  from  the  input  file. 


r-1  0  I  ENTER  I 


reads  10  lines  from  the  input  file. 


r«  |  ENTER  1 

reads  the  remaining  lines  from  the  input  file. 

If  a  file  contains  no  more  text,  the  screen 
shows  the  »END  OF  file*  message. 
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Wn  Writes  n  lines  to  the  output  file,  starting  with 

the  current  line.  It  displays  all  lines  that  are 
deleted  from  the  buffer.  For  example, 


w    ENTER 


writes  the  current  line  to  the  output  file. 


wS  I  ENTER  I 


writes  the  current  line  and  the  next  four  lines 
to  the  output  file. 


w«     ENTER 


writes  all  lines  from  the  current  line  to  the 
end  of  the  buffer  to  the  output  file. 

For  some  practice  in  using  the  commands  that  read  and  write 
OS-9  text  files,  turn  to  Sample  Session  4  in  this  chapter. 

Conditionals  and  Command  Series  Repetition 

When  a  command  cannot  be  executed,  the  editor  sets  an  internal 
flag,  and  the  screen  shows  FAIL,  For  example,  if  you  try  to  read 
from  a  file  that  has  no  more  text,  the  editor  sets  the  fail  flag.  A 
set  fail  flag  means  that  the  editor  cannot  execute  any  more  com- 
mands until  Edit  encounters  one  of  the  following: 

•  The  end  of  a  command  line  typed  from  the  keyboard. 

•  The  end  of  the  current  loop.  Any  loops  that  are  more 
deeply  nested  are  skipped.  (See  the  repeat  command.) 

•  A  colon  (:)  command.  Since  loops  nested  deeper  than  the 
current  level  are  skipped,  any  occurrences  of  :  that  are 
in  a  more  deeply  nested  loop  are  also  skipped. 
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Following  are  the  commands  and  conditions  that  set  the  fail  flag; 

<  Trying  to  move  the  edit  pointer  beyond  the 

beginning  of  the  edit  buffer. 

>  Trying  to  move  the  edit  pointer  beyond  the   + 

end  of  the  buffer. 

S,C  Not  finding  a  string  that  was  searched  for. 

G  No  text  left  in  the  secondary  buffer. 

R  No  text  left  in  the  read  file. 

P,W  No  text  left  in  the  primary  buffer. 

If  you  specify  an  asterisk  for  the  repeat  count  on  these  com- 
mands, Edit  does  not  set  the  fail  flag,  because  an  asterisk  usu- 
ally means  continue  until  there  is  nothing  more  to  do.  The 
following  commands  explicitly  set  the  fail  flag  if  some  condition 
is  not  true. 

.EOF  Tests  for  end-of-file.  .EOF  succeeds  if  there  is 

no  more  text  to  read  from  a  file.  Otherwise,  it 
sets  the  fail  flag. 

.NEOF  Tests  for  not  end-of-file.  .NEOF  succeeds  if 

there  is  text  to  read  from  the  file.  Otherwise, 
it  sets  the  fail  flag. 

.EOB  Tests  for  end-of-buffer.  .EOB  succeeds  if  the 

edit  pointer  is  at  the  end  of  the  buffer.  Other- 
wise, it  sets  the  fail  flag. 

.NEOB  Tests  for  not  end-of-buffer.  .NEOB  succeeds  if 

the  edit  pointer  is  not  at  the  end  of  the  buffer. 
Otherwise,  it  sets  the  fail  flag, 

.EOL  Tests  for  end-of-line.  This  test  succeeds  if  the 

edit  pointer  is  at  the  end  of  the  line.  Other- 
wise, it  sets  the  fail  flag. 

.NEOL  Tests  for  not  end-of-line.  .NEOL  succeeds  if 

the  edit  pointer  is  not  at  the  end  of  the  line. 
Otherwise,  it  sets  the  fail  flag, 

.ZERO  n  Tests  for  zero  value.  .ZERO  succeeds  if  n 

equals  zero.  Otherwise,  it  sets  the  fail  flag. 
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.STAR  n 


.STR  str 


.NSTR  str 


.S 


-F 


[commands]n 


Tests  for  star  (asterisk).  .STAR  succeeds  if  n 
equals  65,535  ("*").  Otherwise,  it  sets  the  fail 
flag. 

Tests  for  string  match.  .STR  succeeds  if  the 
characters  at  the  current  position  of  the  edit 
pointer  match  the  string.  Otherwise,  it  sets 
the  fail  flag. 

Tests  for  string  mismatch.  .NSTR  succeeds  if 
the  characters  at  the  current  position  of  the 
edit  pointer  do  not  match  the  string.  Other- 
wise, it  sets  the  fail  flag. 

Exits  and  succeeds.  This  is  an  unconditional 
exit  from  the  innermost  loop  or  macro.  The 
fail  flag  clears  after  the  exit. 

Exits  and  fails.  This  is  an  unconditional  exit 
from  the  innermost  loop  or  macro.  The  fail 
flag  sets  after  the  exit. 

Repeats  the  commands  n  times.  Left  and  right 
brackets  form  a  loop  that  repeats  the  enclosed 
commands  n  times.  (The  loop  must  be 
repeated  at  least  once.)  If  you  enter  the  loop 
command  from  the  keyboard,  it  must  all  be  on 
one  line.  If  it  is  part  of  a  macro,  however,  it 
can  span  several  command  lines.  For  example, 


[1]    B  [  ENTER  1 


repeats  the  L  command  five  times. 

Note:  This  is  not  the  same  as  L5,  which  executes  the  L 
command  only  once  and  has  5  as  its  parameter. 

[  +  1*  Displays  lines  starting  with  the  next  line  up 

to  the  end  of  the  buffer  and  moves  the  edit 
pointer  to  the  end  of  the  buffer. 

This  command  repeats  until  the  operation 
reaches  the  end  of  the  buffer.  Then,  when  the 
command  tries  to  move  the  edit  pointer  past 
the  end  of  the  buffer,  Edit  sets  the  fail  flag, 
terminates  the  loop,  then  clears  the  fail  flag. 
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commands  Executes  the  commands  following  the  colon 
based  on  the  state  of  the  fail  flag.  For 
example; 

FAIL  FLAG  CLEAR  Skips  all  commands 
that  follow  the  colon  (:) 
up  to  the  end  of  the  cur- 
rent loop  or  macro, 

FAIL  FLAG  SET         Clears  the  fail  flag,  and 

executes  the  commands 
that  follow  the  colon  (:). 

Below  is  a  command  line  that  deletes  all  lines 
that  do  not  begin  with  the  letter  A. 


[CTRLlm  I     .neob    C     .str"A"    +     :    d    ] 


ENTER 


Q  moves  the  edit  pointer  to  the  beginning  of 
the  buffer.  The  outer  loop  tests  for  the  end  of 
the  buffer  and  terminates  the  loop  when  it  is 
reached. 

The  inner  loop  tests  for  A  at  the  beginning  of 
the  line.  If  there  is  an  A,  the  +  command  is 
executed.  Otherwise,  it  executes  the  D 
command. 

Below  is  a  command  that  searches  the  current 
line  for  "find  it".  If  the  command  finds  the 
text,  it  displays  the  line.  Otherwise,  the  com- 
mand line  fails  and  the  screen  shows 
*    FAIL    *. 

[     .eol    v0    -0    v     .f.   :     .str"find    it" 


-0     .s     :     [>]     ]*  I  ENTER  I 


.EOL  VO  -0  V  ,F  tests  to  determine  if  the  edit 
pointer  is  at  the  end  of  the  line.  If  it  is,  Edit 
turns  off  the  verify  mode  to  prevent  -0  from 
displaying  the  line.  Then  it  turns  verify  back 
on,  and  .F  ends  the  loop. 
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If  the  edit  pointer  is  not  at  the  end  of  the  line, 
the  .STR  command  searches  for  "find  it"  at  the 
current  position  of  the  edit  pointer.  If  it  is  at 
the  end  of  the  line,  Edit  executes  the  -0  .S 
commands.  This  execution  moves  the  edit 
pointer  back  to  the  beginning  of  the  line,  dis- 
plays the  line,  and  terminates  the  loop.  Other- 
wise, the  >  command  moves  the  edit  pointer 
to  the  next  position  in  the  line. 

The  brackets  prevent  the  command  from  fail- 
ing and  terminating  the  main  loop  if  the  end 
of  the  buffer  is  reached. 

Edit  Macros 

Edit  macros  are  commands  you  create  to  perform  a  specialized 
or  complex  task.  For  example,  you  can  replace  a  frequently  used 
series  of  commands  with  a  single  macro.  First,  save  the  series  in 
a  macro.  Then  each  time  you  need  it,  type  a  period  followed  by 
the  macro's  name  and  parameters.  The  editor  responds  as  if  you 
had  typed  the  series  of  commands. 

Macros  consist  of  two  main  parts,  the  header  and  the  body.  The 
header  gives  the  macro  a  name  and  describes  the  type  and  order 
of  its  parameters.  The  body  consists  of  any  number  of  ordinary 
commands.  (Except  for  a  space  character  and  |  enter  |,  you  can  use 
any  command  in  a  macro). 

Note:  Macros  cannot  create  new  macros. 

To  create  a  macro,  first  define  it  with  the  .MAC  command.  Then 
enter  the  header  and  body  in  the  same  manner  as  you  enter  text 
into  an  edit  buffer.  When  you  are  satisfied  with  the  macro,  close 
its  definition  by  pressing  Qj]  |  enter  ).  This  command  returns  you 
to  the  normal  edit  mode. 

Macro  Headers.  A  macro  header  must  be  the  first  line  in  each 
macro.  It  consists  of  a  name,  and  a  "variable  list"  that  describes 
the  macro's  parameters,  if  there  are  any.  The  name  consists  of 
any  number  of  consecutive  letters  and  underline  characters.  Fol- 
lowing are  possible  macro  names: 

del_all 

trim_spaces 

LIST 

CHANGE_X_TO_Y 
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Although  you  can  make  a  macro  name  any  length,  it  is  better  to 
keep  it  short,  because  you  must  spell  it  the  same  way  each  time 
you  use  it.  You  can  use  upper-  and  lowercase  letters  or  a 
mixture. 

Using  Macros.  Like  other  commands,  you  can  give  parameters 
to  macros  so  that  they  are  able  to  work  with  different  strings 
and  with  different  numbers  of  items.  Macros  are  unable  to  use 
parameters  directly.  Instead,  Edit  passes  the  parameters  on  to 
the  commands  that  make  up  the  macro. 

To  pass  the  macro's  parameters  to  these  commands,  use  the 
variable  list  in  the  macro  header  to  tell  each  command  which  of 
the  macro's  parameters  to  use.  Each  variable  in  the  variable  list 
represents  the  value  of  the  macro  parameter  in  its  corresponding 
position.  Use  the  corresponding  variable  wherever  the  parame- 
ter's value  is  needed. 

The  two  types  of  variables  are  numeric  and  string.  A  numeric 
variable  is  a  variable  name  preceded  by  the  #  character.  A 
string  variable  is  a  variable  name  preceded  by  a  $  character. 
Variable  names,  like  macro  names,  are  composed  of  any  number 
of  consecutive  letters  and  underline  characters.  Examples  of 
numeric  variables  are: 

#N 

#ABC 

#LONG_NUMBER_VARIABLE 

Examples  of  string  variables  are; 

$A 
$B 

$STR 
$STR_A 

Slower  _case_variable_name 

The  function  of  the  edit  macro  below  is  the  same  as  that  of  the  S 
command,  to  search  for  the  next  n  occurrences  of  a  string. 
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The  first  line  of  the  macro  is  the  macro  header.  It  assigns  the 
macro's  name  as  SRCH.  It  also  specifies  that  the  macro  needs 
one  numeric  parameter  (#N)  and  one  string  parameter  ($STR), 
The  entire  body  of  the  macro  is  the  second  line.  This  example 
passes  both  of  the  macro's  parameters  to  the  S  command,  which 
does  the  actual  searching. 

SRCH  #N  SSTR 
S  *N  $STR 

Here  is  an  example  of  how  to  execute  this  macro: 

.SRCH    15    "string"  fENTERl 

In  the  next  example,  the  order  of  the  parameter  is  reversed. 
Therefore,  when  executing  the  macro,  use  the  reverse  order.  The 
macro  structure  is: 

SRCH  SSTR  #N 
S  #N  SSTR 

Specify  the  parameters  for  the  "S"  command  in  the  proper  order 
since  it  is  only  the  "SRCH"  macro  that  is  changed.  The  following 
example  shows  how  to  execute  this  macro.  The  order  of  the 
parameters  corresponds  directly  to  the  order  of  the  variables  in 
the  variable  list. 

.SRCH    "string"    15  flNTER~| 
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Ma,cro  Commands 

Although  macro  editing  has  the  same  functions  as  text  editing, 
the  macro  mode  also  includes  some  special  commands.  The 
macro  commands  you  can  use  are  as  follows: 

!  text  Places  comments  inside  a  macro.  Ignores  the 

remainder  of  the  line  following  the  !  command. 
This  command  lets  you  include,  as  part  of  a 
macro,  a  short  description  of  what  it  does. 
Comments  can  help  you  remember  the  func- 
tion of  a  macro.  For  example: 

I 

<">!  Move  the  pointer  to  the  top  of  the 

buffer. 
I*!       Display  all  lines  of  text. 
I 

In  this  example  there  are  four  comments.  Two 
are  empty,  and  two  describe  the  commands 
that  precede  them. 

.macro  name       Executes  the  macro  specified  by  the  name  fol- 
lowing the  period  (.).  For  example: 


. mymacro  | ENTER  1 
.list     0  I  ENTER  I 


.trim    "    "  I  ENTER  ) 

.merge   "    file_a    "    file    b    b"  |  ENTER  | 


.MAC  str  Creates  a  new  macro  or  opens  the  definition  of 

an  existing  one  so  that  it  can  be  edited.  To 
create  a  new  macro,  specify  an  empty  string. 
For  example, 


ENTER 


creates  a  new  macro  and  puts  you  into  the 
macro  mode. 
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.SAVE  strl 
str2 


The  screen  shows  M;  instead  of  E:  when  the 
editor  is  in  the  macro  mode.  To  edit  a  macro 
that  already  exists,  specify  the  macro's  name. 
For  example, 


.mac    "mymacro"  |  ENTER! 

opens  the  macro  "MYMACRO"  for  editing. 

When  a  macro  is  open,  edit  it,  or  enter  its  def- 
inition with  the  same  commands  you  use  in  a 
text  buffer.  After  you  edit  the  macro,  press  [a] 
[  enter  |  to  close  its  definition  and  return  to  the 
edit  mode.  The  first  line  of  the  macro  must 
begin  with  a  name  that  is  not  already  used  in 
order  to  close  the  definition  and  return  to 
Edit. 

Saves  macros  on  an  OS-9  file.  Strl  specifies  a 
list  of  macros  to  be  saved.  Separate  the  macro 
names  with  spaces.  Str2  specifies  the  pathlist 
for  the  file  on  which  you  want  to  save  the 
macros.  For  example: 


•  save    "mymacr o"myf  1  le"  [ENTER] 

saves  the  macro  "MYMACRO"  on  the  file 

"MYFILE". 


.save    "maoa    rnacb   macc"mf  1  le"  I  ENTER  I 


saves  the  macros  "MACA,"  "MACB,"  and 
"MACC"  on  the  file  "MFILE". 

.SEARCH  n         Searches  the  text  file  buffer  for  the  specified 

str  string.  When  a  match  is  found,  it  stops  and 

displays  that  line.  The  n  option  permits  a 

search  for  the  nth  occurrence  of  a  string 

match.  This  command  is  the  same  asSn  str. 
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.LOAD  str 


.DEL  str 


.DIR 


.CHANGE  n 

strl  str2 


Loads  macros  from  an  OS-9  file.  As  each 
macro  loads,  Edit  verifies  that  no  other  macro 
already  exists  with  the  same  name.  If  one 
does,  the  macro  with  the  duplicate  name  does 
not  load,  and  Edit  skips  to  the  next  macro  on 
the  file.  Edit  displays  the  names  of  all  macros 
it  loads.  For  example, 


.  load    "macrof  ile"    ENTER 


loads     the    macros    in    the    file    called 
MACROFILE. 


.load-  "myf  ile"  [  ENTER  1 

loads  the  macros  in  the  file  called  MYFILE. 

Deletes  the  macro  specified  by  the  string.  For 
example, 


.del    "mymacro"  | ENTER] 
deletes  the  macro  called  MYMACRO. 
.del    "Hat"  I  ENTER  j 

deletes  the  macro  called  LIST. 

Displays  the  current  edit  buffer  area.  All  edit 
buffers  and  macros  currently  in  memory  are 
displayed. 

Changes  the  occurrence  of  strl  to  str2.  The  n 
option  permits  n  occurrences  of  strl  to  be 
changed  to  str2. 
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Q 


Ends  a  macro  edit  session  and  returns  you  to 
the  normal  edit  mode.  For  example: 

Search_and_Delete    #N    $STR 
!This    example   MACRO    is    used    to 

!  chec  k 

!the  string  at  the  beginning  of 
!an  #N  number  of  lines.  If  the 
(string  matches,  it  will  delete 
ithat  line  from  the  text  buffer 
!f ile. 

SNDTE:  The  way  the  editor 
■processes  a  MACRO  causes  it  to 
!see  any  parameters  in  the  outer 
lloop  first.  Thus,  the  #N 
(parameter  is  processed  before 
!the  STR  parameter. 


[*] 


[ 

,  neob 


[ 

.nstr  $str 


] 


End  of  Macro 


SMove  to  start  of 

■edit  buffer 

Istart  of  outer  loop 

Itest  for  buffer  end 

istart  of  inner  loop 

■test  for  not  string 

! mot  ch 

!go  to  next  line  if 

! no  ma t ch 

!  if  f lag  clear  skip 

!next  command 

Idelete  line  if  flag 

{set 

Send   of    inner    loop 

! end    of    outer    loop 


For  practice  in  using  macro  commands,  turn  to  Sample  Session  5 
in  this  chapter. 
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Sample  Session  1 

Clear  the  buffer  by  deleting  its  contents. 

You  Type:  |"ctrl"||T1  D*  I  enter  | 

Screen  Shows:  *D* 

Insert  three  lines  into  the  buffer.  Begin  each  line  with  a  space, 
which  is  the  command  for  inserting  text. 

You  Type:  dmy  first  line  [!nteb~| 

QMY    SECOND    LINE  [  ENTER  1 


GMY   THIRD   LINE  1 ENTER  | 
Screen  Shows:  MY  F I RST  L I NE 

MY    SECOND    LINE 
MY   THIRD   LINE 

Move  the  edit  pointer  to  the  top  of  the  text.  The  editor  always 
considers  the  first  character  you  type  a  command. 

Note:  |  ctrl  [|T|  always  shows  *  on  the  screen.  Typing  -  *  also 
moves  the  edit  pointer  to  the  beginning  of  a  buffer. 

You  Type:  L^BDLlI  I  enter  | 

Screen  Shows:  * 

List  (display)  the  first  line  you  inserted  into  the  buffer. 
"You  Type:  L  |  enter  | 

Screen  Shows:  L 

MY    FIRST    LINE 

Display  the  first  two  lines  you  inserted  into  the  buffer. 
You  Type:  L2  I  enter  I 

Screen  Shows:  L2 

MY  FIRST  LINE 
MY  SECOND  LINE 

Move  to  the  next  line  and  display  it. 
You  Type:  |  enter  | 

Screen  Shows:  MY  SECOND  LINE 

Move  to  the  next  line  and  display  it. 
You  Type:  |  enter  | 

Screen  Shows:  my  THIRD  LINE 
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Using  L,  display  text  beginning  at  the  position  of  the  edit 
pointer. 

You  Type:  l  I  enter  1 

Screen  Shows:  L 

MY    THIRD    LINE 

Insert  a  line  into  the  buffer, 

Note:  In  the  next  sample  you  see  that  the  insert  comes 
before  the  current  position  of  the  edit  pointer. 

You  Type:  DINSERT  A  LINE  |WflR~| 

Screen  Shows:  insert  a  line 

The  following  command  line  consists  of  more  than  one  command. 
I  ctrl  \{T\  \  enter  I  moves  the  edit  pointer  to  the  top  of  the  text.  I  dis- 
plays the  text,  and  the  asterisk  (»)  following  L  indicates  that  text 
is  displayed  through  to  the  end  of  the  buffer. 
You  Type:  rcTRD|T|L«  ["enter"! 

Screen  Shows:  *L* 

MY    FIRST    LINE 

MY    SECOND   LINE 

INSERT    A    LINE 

MY    THIRD   LINE 

Show  the  position  of  the  edit  pointer. 
You  Type:  L  [enterI 

Screen  Shows:  L 

MY    FIRST    LINE 

Move  the  edit  pointer  forward  two  lines  and  display  the  lines. 
You  Type:  +  z  (  enter  | 

Screen  Shows:  +  2 

INSERT   A   LINE 

Display  all  lines  from  the  edit  pointer  to  the  end  of  the  buffer. 
You  Type:  L  *  I  enter  I 

Screen  Shows:  L  * 

INSERT   A    LINE 
MY    THIRD   LINE 

Move  the  edit  pointer  to  the  end  of  the  buffer. 
You  Type:  /  |  enter  | 

Screen  Shows:  / 

Determine  if  the  edit  pointer  is  at  the  end  of  text.  Since  the 
screen  shows  no  more  lines,  the  edit  pointer  is  at  the  end-of-text. 

You  Type:  L »  |  enter  | 

Screen  Shows:  L » 
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Insert  two  more  lines. 

You  Type:  ififth  line  [mfm] 

CLAST   LINE  |  ENTER  | 
Screen  Shows:  fifth  LINE 

LAST   LINE 

Move  the  edit  pointer  back  one  line,  and  display  the  line. 
You  Type:  -2  |  enter  | 

Screen  Shows:  -  2 

FIFTH    LINE 

Move  the  edit  pointer  back  two  lines,  and  display  the  line. 
You  Type:  -  3  j  enter  | 

Screen  Shows:  -  3 

MY  SECOND  LINE 

Move  the  edit  pointer  three  characters  to  the  right  and  display 
the  remainder  of  the  line. 

Note:  You  must  put  spaces  between  commands. 
You  Type:  >  3  L  [  enter  I 

Screen  Shows:  >3  l 

SECOND   LINE 

Display  the  characters  that  precede  the  edit  pointer  on  the  cur- 
rent line. 

■&u  Type:  x  |  enter  | 

Screen  Shows:  x 

MY 

Move  the  edit  pointer  to  the  end  of  the  current  line. 
You  Type:  +  0  |  enter  I 

Screen  Shows:  +  0 

Determine  if  the  edit  pointer  is  at  the  end  of  the  line.  It  is,  since 
the  screen  shows  no  lines. 

You  Type:  L  |  enter  | 

Screen  Shows:  L 

Display  the  characters  that  precede  the  edit  pointer  on  the  cur- 
rent line. 

You  Type:  x  |  enter  I 

Screen  Shows:  x 

MY  SECOND  LINE 
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Move  the  edit  pointer  back  to  the  beginning  of  the  current  line. 
You  Type:  -  0  I  enter  | 

Screen  Shows:  -0 

MY  SECOND  LINE 

Determine  if  the  edit  pointer  is  at  the  beginning  of  the  line. 
Since  the  screen  shows  no  lines,  the  pointer  is  at  the  beginning. 

You  Type:  x  |  enter  I 

Screen  Shows:  x 

Go  to  the  beginning  of  the  text. 

You  Type:  CcJEDLD  I  enter  I 

Screen  Shows:  A 

Insert  a  line  of  14  asterisks. 

You  Type:  1 1 4"*"  |  enter  [ 

Screen  Shows:  1 1 4  "  •  ■  ■ 

************** 

Insert  an  empty  line. 

You  Type:  I ""  1  enter  I 

Screen  Shows:  I"" 

Move  to  the  top  of  the  text,  and  display  all  lines  in  the  buffer. 
You  Type:  rcTRTTflL*  |  enter  | 

Screen  Shows:  AL* 

************** 

MY  FIRST  LINE 
MY  SECOND  LINE 

INSERT  A  LlNE 
MY  THIRD  LINE 
FIFTH  LINE 
LAST  LINE 


Move  the  edit  pointer  forward  two  lines. 
You  Type:  +  2  |  enter  ) 

Screen  Shows:  +2 

MY    FIRST    LINE 

Extend  the  line  with  XXX.  

You  Type:  E"   xxx"  UnterI 

Screen  Shows:  E "  x  x  x  •• 


MY    FIRST   LINE    XXX 


Display  the  current  line. 
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Note:  The  previous  E  command  moved  the  edit  pointer  to 
the  next  line. 

You  Type:  i_  1  enter  | 

Screen  Shows:  L 

MY  SECOND  LINE 

Extend  three  lines  with  YYY. 

You  Type:  E3"L"YYY"  I  enter  | 

Screen  Shows:  E3"  yyy" 

MY    SECOND   LINE    YYY 
INSERT   A   LINE    YYY 
MY    THIRD    LINE    YYY 

Move  back  2  lines. 

You  Type:  -2  I  enter  | 

Screen  Shows:  -  2 

INSERT    A    LINE    YYY 

Move  the  edit  pointer  to  the  end  of  the  line  and  then  move  the 
edit  pointer  back  four  characters.  Display  the  current  line,  start- 
ing at  the  edit  pointer. 

You  Type:  +0   <4  L  |  enter  | 

Screen  Shows:  +0   <4  L 

YYY 

Truncate  the  line  at  the  current  position  of  the  edit  pointer.  This 
command  removes  the  YYY  extension. 

You  Type:  U  I  enter  | 

Screen  Shows:  u 

INSERT    A    LINE 

Go  to  the  top  of  the  text  and  display  the  contents  of  the  buffer. 
You  Type:  |  Ctrl  Iff]  L  *  |  enter  | 

Screen  Shows:  AL* 

MY  FIRST  LINE  XXX 
MY  SECDND  LINE  YYY 
INSERT  A  LINE 

MY  THIRD  LINE  YYY 
FIFTH  LINE 
LAST  LINE 
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Delete  the  current  line  and  the  next  line. 
You  Type:  D2  |  enter  | 

Screen  Shows:  D2 

******** *•**  * • 

Move  the  edit  pointer  forward  two  lines. 
You  Type:  +  2  [  enter  1 

Screen  Shows:  +  2 

INSERT    A    LINE 


Delete  this  line. 

You  Type:  D  |  enter  | 

Screen  Shows:  D 


INSERT   A   LINE 

Display  the  current  line. 

You  Type:  L  Center! 

Screen  Shows:  L 

MY   THIRD   LINE    YYY 

Move  the  edit  pointer  to  the  right  three  characters  and  display 
the  text. 

You  Type:  >3  L  |  enter  I 

Screen  Shows:  >3  L 

THIRD   LINE    YYY 

Kill  (delete)  the  11  characters  that  constitute  THIRD  LINE. 
You  Type:  K 1 1  |  enter  | 

Screen  Shows:  K 1 1 

THIRD   LINE 

Go  to  the  beginning  of  the  line  and  display  it. 
You  Type:  -  0  [  enter  I 

Screen  Shows:  -  0 

MY    YYY 

Concatenate  (combine)  two  lines.  Move  the  edit  pointer  to  the 
end  of  the  line;  delete  the  character  at  the  end  of  the  line;  move 
the  edit  pointer  back  to  the  beginning  of  the  lines.  Display  the 
line. 

You  Type:  +0   K  -0  |  enter  | 

Screen  Shows:  0   K   -  0 

MY    YYYFIFTH   LINE 

Separate  the  two  lines  by  inserting  an  end-of-line  character. 
You  Type:  >6  1/  /  |  enter  I 

Screen  Shows:  >6   1/   / 

MY    YYY 
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Note:  The  end  of  line  character  is  inserted  before  the  current 
position  of  the  edit  pointer.       

You  Type:  L  I  enter  | 

Screen  Shows:  L 

FIFTH    LINE 


Sample  Session  2 

Clear  the  buffer  by  deleting  its  contents. 
You  Type: 


Insert  lines. 

You  Type: 


|  CTRL  ||  7  |  D*  |  ENTER  | 

DONE   TWO   THREE 
DONE  |  ENTER  | 
ICTWO  |  ENTER  | 

GLTJTHREE  |  ENTER  | 
DONE    TWO    THREE 

DONE  |  ENTER  | 

ZCTWO  [ENTER] 

LTDTHREE  (ENTER) 

.  0  lENTER 


2 .  0  [ENTER 


Screen  Shows: 


DONE  TWO  THREE  3.  0  |  ENTER  | 
ONE  TWO  THREE  1 .0 
ONE 
TWO 
THREE 
ONE  TWO  THREE  2.0 
ONE 
TWO 
THREE 
□  NE  TWO  THREE  3.0 


Go  to  the  top  of  the  text,  and  display  all  lines  in  the  buffer. 


You  Type: 

Screen  Shows: 


rjTRDCD  L*  I  ENTER  j 

«!_• 

ONE    TWO   THREE    1 . 

ONE 
TWO 
THREE 
ONE  TWO  THREE  2. 
ONE 
TWO 
THREE 
□NE  TWO  THREE  3. 
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Search  for  the  next  occurrence  of  TWO. 

You  Type:  s  "TWO"  [  enter  | 

Screen  Shows:  S"TW0" 

ONE   TWO   THREE    1  .0 

Search  for  all  occurrences  of  TWO  that  are  between  the  edit 
pointer  and  the  end  of  the  buffer. 

You  Type:  s«/two/  |  enter  l 

Screen  Shows:  s  *  /  T  w  o  / 

ONE  TWO  THREE  1 .  0 
TWO 

ONE  TWO  THREE  2,0 

TWO 
ONE  TWO  THREE  3.0 

Go  to  the  top  of  the  buffer,  and  change  the  first  occurrence  of 
THREE  to  ONE.  

You  Type:  [ctrQE!  c/three/one/  I  enter  I 

Screen  Shows:  *  c/three/dne/ 

ONE   TWO    ONE    1.0 

Move  the  edit  pointer  to  the  top  of  the  buffer.  Set  the  anchor  to 
Column  2,  and  then  use  the  search  command  to  find  each  occur- 
rence of  TWO  that  begins  in  Column  2.  Skip  all  other 
occurrences. 

You  Type:  (ctSDE  A2  S*/TWO/  I  enter  I 

Screen  Shows:  A  A  2  s»/two/ 

TWD 
TWO 

Move  the  edit  pointer  to  the  top  of  the  buffer.  Set  the  anchor  to 
Column  1,  and  change  each  occurrence  of  ONE  that  begins  in 
that  column  to  XXX. 

Note:  ONE  in  Line  1  is  not  changed,  since  it  does  not  begin 
in  Column  1. 

You  Type:  ("ctrTIT]  ftc«/ONE/xxx/  l enter | 

Screen  Shows:  *  fiC«/ONE/XXX/ 

XXX  TWO  ONE  1.0 

XXX 

XXX  TWO  THREE  2. 0 

XXX 

XXX  TWD  THREE  3.0 
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Go  to  the  top  of  the  buffer,  and  display  the  text. 
You  Type:  QnRT)rJ]L. «  |  enter  1 

Screen  Shows:  L  » 

XXX    TWO    ONE    1.0 
XXX 
TWO 
THREE 
XXX    TWO   THREE    2. 0 
XXX 
TWO 
THREE 
XXX    TWO    THREE    3.0 

Change  the  remaining  ONE  to  XXX. 

Note:  The  anchor  is  no  longer  set.  It  is  reset  to  zero  after 
each  command  is  executed. 

You  Type:  c/one/xxx/  |  enter  I 

Screen  Shows:  c/ONE/xxx/ 

XXX    TWO    XXX    1.0 

Move  to  the  beginning  of  the  current  line. 
"Km  Type:  -0  |  enter  I 

Screen  Shows:  -  0 

XXX    TWO    XXX     1 .0 

Change  three  occurrences  of  XXX  to  ZZZ. 

You  Type:  C3/XXX/ZZZ/  |  enter  | 

Screen  Shows:  C3/XXX/ZZZ/ 

zzz  two  xxx  1.0 
zzz  two  zzz  1 . 0 
zzz 


Sample  Session  3 

Clear  the  buffer  by  deleting  its  contents: 

You  Type:  [ctrTIITI  D*  l  enter  l 
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Display  the  directory  of  buffers  and  macros.  The  dollar  sign  ($) 
identifies  the  secondary  buffer  as  Buffer  0,  The  asterisk  (*)  iden- 
tifies the  primary  buffer  as  Buffer  1.  Edit  has  no  macros  defined. 
This  is  the  initial  environment  when  you  start  Edit. 

You  Type:  .  D I R  [  enter  | 

Screen  Shows:  ,  D I R 

BUFFERS: 
i  0 


MACROS: 

Insert  some  lines  into  Buffer  1  so  that  later  you  can  identify  it. 

%u  Type:  DBUFFER   ONE   1  . 0  (JNTER] 

DBUFFER   ONE   2.0  fENTER"] 

DBUFFER    ONE    3  .  0  [  ENTER  | 

DBUFFER    ONE    4  .  0  [  ENTER  I 


Screen  Shows: 


BUFFER  ONE  1.0 
BUFFER  ONE  2.0 
BUFFER  ONE  3.0 
BUFFER  ONE  4.0 


Display  the  text  in  Buffer  1. 
You  Type: 
Screen  Shows: 


CTRL|T}  L*  |  ENTER  [ 
"I* 

BUFFER  ONE  1.0 

BUFFER  ONE  2.0 

BUFFER  ONE  3.0 

BUFFER  ONE  4.0 

Make  Buffer  0  the  primary  buffer,  Buffer  1  becomes  the  second- 
ary buffer. 

You  Type:  B0  [  enter  | 

Screen  Shows:  bb 

Display  the  directory  of  buffers  and  macros. 

Note:  The  symbols  identifying  the  buffers  are  now  reversed. 
You  Type:  .  D I R  |  enter  I 

Screen  Shows:  .  D I R 

BUFFERS: 
$  1 

»  0 

MACROS: 
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Insert  some  lines  into  Buffer  0. 

15>u  Type:  DBUFFER  ZERO   1  .  0  I  ENTER  I 


GBUFFER   ZERO   2 

CBUFFER   ZERO    3 

Screen  Shows: 

GBUFFER   ZERO    4 
BUFFER    ZERO    1 . 

BUFFER   ZERO   2. 

BUFFER   ZERO    3. 

BUFFER   ZERO    4, 

lay  the  text  in  Buffer  0 

You  Type: 

Screen  Shows: 

I  CTRL  ][  7  |  L  »  |  ENTER  | 

BUFFER   ZERO    1 

BUFFER   ZERO   2 

BUFFER   ZERO    3 

BUFFER   ZERO    4 

Switch  to  Buffer  1, 
You  Type: 
Screen  Shows: 

Display  the  text  in  Buffer  1. 
"Sou  Type: 
Screen  Shows: 


B  |  ENTER  I 
B 


CTRLTTl  L*  I  ENTER  I 


BUFFER  ONE  1 . 

BUFFER  ONE  2. 

BUFFER  ONE  3. 

BUFFER  ONE  4, 

Move  the  edit  pointer  to  Line  3  in  this  buffer. 
You  Type: 
Screen  Shows: 

OHE     3 

Switch  to  Buffer  0. 
You  Type: 
Screen  Shows: 

Display  the  text  in  Buffer  0. 
You  Type: 
Screen  Shows:  L  « 

BUFFER   ZERD    1 . 

BUFFER   ZERD   2. 

BUFFER    ZERO    3. 

BUFFER   ZERO    4. 


+  2  |  ENTER  | 

*2 
BUFFER 

B0  |  ENTER  | 

B0 

L*  I  ENTER  | 

0   | ENTER  | 

0   ! ENTER  I 


0  I  ENTER  I 
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Move  the  edit  pointer  to  Line  2  in  this  buffer. 
You  Type:  +  |  enter  I 


Screen  Shows: 


BUFFER    ZERO    2.0 


Switch  to  Buffer  1. 

You  Type:  B  |  enter  | 

Screen  Shows:  B 

Display  the  text  in  Buffer  1  from  the  current  position  of  the  edit 
pointer. 

Note:  The  position  of  the  edit  pointer  has  not  changed  since 
you  switched  to  Buffer  0. 

You  Type:  l  *  |  enter  | 

Screen  Shows:  L  * 

BUFFER  ONE  3.0 
BUFFER  ONE  4.0 

Switch  to  Buffer  0. 

You  Type:  B0  I  enter  I 

Screen  Shows:  B0 

Display  the  text  in  Buffer  0  from  the  current  position  of  the  edit 
pointer. 

Note:  The  position  of  the  edit  pointer  has  not  changed  since 
you  switched  to  Buffer  1. 


You  Type: 

Screen  Shows: 

L»  (ENTER) 

BUFFER 

ZERO    2, 

.0 

BUFFER 

ZERO    3, 

.0 

BUFFER 

ZERO   4. 

,0 

Delete  the  contents  of  Buffer  0. 

You  Type: 

Screen  Shows: 

1  CTRL  II  7  ]  D 

*  | ENTER  ) 

BUFFER 

ZERO    1  . 

.0 

BUFFER 

ZERO    2, 

a 

BUFFER 

ZERO    3. 

.0 

/^~-. 

BUFFER 

ZERO    4. 

0 

Make  Buffer  1  the  primary  buffer  and  Buffer  0  the 
buffer. 

secondary 

You  Type: 
Screen  Shows: 

B  .'  ENTER  | 
B 
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Move  two  lines  from  the  primary  buffer  (Buffer  1)  into  the  sec- 
ondary buffer  (Buffer  0). 

"Sou  Type:  rcfBTUT)  P2  |  enter  | 

Screen  Shows:  AP2 

BUFFER  ONE  1 .0 
BUFFER    ONE   2.0 

Switch  to  Buffer  0,  and  show  that  the  lines  were  moved  to  it. 
You  Type:  B0fCTRTl|T)L«  [enter I 

Screen  Shows:  B0Al_* 

BUFFER  DNE  1 . 0 
BUFFER    DNE    2.0 

Switch  to  Buffer  1.  Go  to  the  bottom  of  the  buffer,  and  get  the 
text  out  of  the  secondary  buffer. 

You  Type:  B/G*  [enter] 

Screen  Shows:  B/G* 

BUFFER  ONE  1.0 
BUFFER    ONE    2.0 

Show  the  contents  of  the  buffer. 

Note:  The  order  of  the  lines  is  changed  as  a  result  of  mov- 
ing the  text. 

You  Type;  [cmIJT]L*  |  enter  I 

Screen  Shows:  "L* 

BUFFER  ONE  3.0 
BUFFER  ONE  4.0 
BUFFER  ONE  1.0 
BUFFER   ONE    2.0 

Move  two  lines  into  the  secondary  buffer. 
You  Type:  P2  [  enter  | 

Screen  Shows:  P2 

BUFFER  ONE  3.0 
BUFFER  ONE  4.0 

Move  to  the  bottom  of  the  buffer,  and  get  the  lines  back  out  of 
the  secondary  buffer. 

You  Type:  /G*  |  enter  | 

Screen  Shows:  /G* 

BUFFER  ONE  3.0 
BUFFER  ONE  4.0 
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Show  that  the  order  of  the  lines  is  restored- 


You  Type: 

S  CTRL  H  7  |L  • 

Screen  Shows: 

L* 

BUFFER   ONE    1 

BUFFER    ONE    2 

BUFFER    DNE    3 

BUFFER    ONE    4 

Sample  Session  4 

Clear  the  buffer  by  deleting  its  contents: 
You  Type: 

Enter  some  lines  of  text. 
You  Type: 


[JTRLJTJD*  |  ENTER  ] 


Screen  Shows: 


DLINE    ONE  [ENTER | 

CSECOND    LINE    OF    TEXT  |  ENTER  l 

TTHIRD   LINE    OF    TEXT  ["enterI 

DFDURTH   LlNEjjNTEJTl 

DFIFTH   LINE  UnterI 

DLAST   LINE  |  ENTER  | 

LINE    DNE 

SECOND  LINE  OF  TEXT 

THIRD  LINE  OF  TEXT 

FOURTH  LINE 

FIFTH  LINE 

LAST  LINE 

Open  the  file  Oldfile  for  writing.  

You  Type:  .WRlTE"oldf  He"  [enter] 

Screen  Shows:  .WRlTE"oidf lie" 

Write  all  lines  to  the  file. 
You  Type: 
Screen  Shows: 


fCTRrpN*  I  ENTER  | 
AW» 

LINE    ONE 

SECOND  LINE  OF  TEXT 

THIRD  LINE  OF  TEXT 

FOURTH  LINE 

FIFTH  LINE 

LAST  LINE 

•END  OF  TEXT* 


Close  the  file. 
You  Type: 
Screen  Shows: 


.WRITE//  I  ENTER  1 
.WRITE// 
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CTRLir7|L«  j  ENTER  | 


Verify  that  the  buffer  is  empty. 
You  Type; 
Screen  Shows:  AL* 

Open  the  file  Oldfile  for  reading. 

You  Type:  .READ"oldf  ile"  | enter | 

Screen  Shows:  .READ"  oldfile" 

Create  a  new  file  called  Newfile  for  writing. 

YOU  Type:  .WRITE"newf  ile"  t  ENTER  | 

Screen  Shows:  .NRITE"newf ile" 


You  Type: 

Screen  Shows: 


Read  four  lines  from  the  input  file.  The  screen  shows  the  lines  as 
they  are  read  in. 

R4  |  ENTER  [ 

R4 

LINE    ONE 

SECOND  LINE  DF  TEXT 
THIRD  LINE  OF  TEXT 
FOURTH  LINE 

Read  all  the  remaining  text  from  the  file.  The  screen  shows  the 
lines.  When  there  is  no  more  text,  the  screen  shows  the  » END  OF 
FILE*  message. 

You  Type:  R  *  [  enter  I 

Screen  Shows:  R  * 


LINE 

LAST 


FIVE 
LINE 


%u  Type: 
Screen  Shows: 


•END    OF    FILE* 

Go  to  the  top  of  the  buffer,  and  display  the  text  to  make  sure  it 
is  inserted  into  the  buffer. 

rCTRT1|T|L«  |  ENTER  | 

*L« 
LINE  ONE 

SECOND  LINE  OF  TEXT 
THIRD  LINE  OF  TEXT 
FOURTH  LINE 
FIFTH  LINE 
LAST  LINE 
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Write  three  lines  to  the  output  file,  and  display  the  lines. 
You  Type:  N3  [  enter  I 

Screen  Shows:  W3 

LINE    ONE 

SECOND   LINE    OF   TEXT 

THIRD    LINE    OF   TEXT 

Move  to  the  next  line  and  display  it. 
You  Type:  +  |  enter  [ 

Screen  Shows:  + 

FIFTH    LINE 

Show  that  when  writing  lines,  the  editor  starts  at  the  current 
line  and  not  at  the  top  of  the  buffer. 

You  Type:  w  |  enter  | 

Screen  Shows:  n 

FIFTH   LINE 

Go  to  the  top  of  the  buffer,  and  display  the  text  to  be  sure  that 
the  lines  were  written  to  the  output  file. 

You  Type:  rcTHnfTlL*  | enter  | 

Screen  Shows:  *L* 

FOURTH  LINE 
LAST  LINE 

Clear  the  buffer. 

You  Type:  rcTRT||T|D«  I  enter  | 

Screen  Shows:  AD» 

FOURTH  LINE 

LAST  LINE 

Switch  to  Buffer  2.  Open  the  input  file  Oldfile,  and  read  two 
lines  from  it. 

You  Type:      .  B2    .READ"oldf  lie"    R2  fENTERl 

Screen  Shows:  B2   .READ"oldf  ile"  R2 

LINE  ONE 
SECOND  LINE  OF  TEXT 

Switch  to  Buffer  1.  Open  the  input  file  Oldfile  and  read  one  line 

of  text.  

You  Type:  B    .READ"oldf  ile"    R  |  ENTER  | 

Screen  Shows:  B   .READ"oldf  He"  R 

LINE    ONE 
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Switch  to  Buffer  2,  and  read  one  line. 

Note:  Your  place  in  the  file  was  not  tost. 
You  Type:  B2  R  I  enter  I 

Screen  Shows:  B2  R 

THIRD  LINE  OF  TEXT 

Switch  to  Buffer  1,  and  read  one  line  of  text. 

Note:  Your  place  in  the  file  was  not  tost. 
You  Type;  B  R  |  enter  | 

Screen  Shows:  b  r 

SECOND   LINE    OF   TEXT 

Switch  to  Buffer  2,  and  delete  its  contents. 

You  Type:  B2  fc!RTl|T)D*  I  enter  I 

Screen  Shows:  B2  *D» 

LINE    DNE 

SECOND   LINE    OF   TEXT 

THIRD   LINE    OF   TEXT 

Insert  some  extra  lines  into  the  buffer. 

You  Type:  cextra  line  one  j enter  | 

CEXTRA    LINE    TWO  fENTERl 
Screen  Shows;  extra  LINE  one 

EXTRA    LINE   TWO 

Try  to  write  B2  buffer  to  file.  It  fails  because  you  have  not 

opened  a  file  in  this  buffer. 

You  Type:  [ctrT|(T|w»  [enter] 

Screen  Shows:  Aw» 

•FILE  CLOSED* 

Close  the  file  for  Buffer  1,  and  return  to  Buffer  2. 
You  Type:  B  .WRITE//  B2  |  enter  I 

Screen  Shows:  B  .write//  b? 

Open  the  old  "write"  file  for  reading,  and  then  read  it  back  in. 
You  Type:  .READ"newf  ile"    R  ■  |  ENTER  I 

Screen  Shows:  . READ"newf  ile"    R* 

LINE    DNE 

SECDND  LINE  OF  TEXT 
THIRD  LINE  OF  TEXT 
FIFTH  LINE 

•END  OF  FILE* 
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Display  the  contents  of  the  buffer. 

Note:  It  read  the  file  into  the  beginning  of  the  buffer,,  since 
that  was  the  position  of  the  edit  pointer. 
You  Type: 


Screen  Shows: 


[CTRLJITJL*  |  ENTER  | 
"l* 

LINE    ONE 

SECOND  LINE  OF  TEXT 

THIRD  LINE  OF  TEXT 

FIFTH  LINE 

EXTRA  LINE  ONE 

EXTRA  LINE  TWO 


Sample  Session  5 

Delete  all  text  from  the  edit  buffer. 
You  Type: 


CTRLlmD*  I  ENTER  I 


Insert  three  lines. 
You  Type: 

Screen  Shows: 


CLINE    ONE  [  ENTER  | 
DLINE   TWO  |  ENTER  I 
DLINE    THREE  rENTER] 
LINE   ONE 
LINE   TWO 
LINE   THREE 

Create  a  new  macro  using  an  empty  string. 
You  Type:  .  MAC /  /  [  enter  | 

Screen  Shows:  M : 

Display  the  contents  of  the  macro  mode,  which  is  now  open. 

Note:  The  E  prompt  is  now  M. 


You  Type: 

|  CTRL  !|  7  |l_  »  |  ENTER] 

Screen  Shows: 

"L* 

Define  the  macro, 

You  Type: 

DF  I  ND  |  ENTER  | 

□S"TU0"  [  ENTER  | 

Screen  Shows: 

FIND 

S"TW0" 

Display  the  contents  of  the 

macro. 

You  Type: 

[  CTRL  H  7  |l_*  !  ENTER] 

Screen  Shows: 

"L* 

FIND 

S"TWO" 
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Close  the  macro's  definition. 

You  Type:  Q  |  enter  | 

Screen  Shows:  E : 

Display  the  directory  of  buffers  and  macros. 
You  Type:  ,  D I R  j  enter  | 


Screen  Shows:      .  D  r  R 

BUFFERS; 
$        0 
»        1 

MACROS: 
FIND 

Display  the  contents  of  the  edit  buffer. 

You  Type:  fcTRrj|T|L«  rgMTERl 

Screen  Shows:  *  l  » 

LINE  ONE 
LINE  TWO 
LINE  THREE 

Use  the  FIND  macro  to  find  the  string  TWO. 
You  Type:  .  n  nd  [Wm] 

Screen  Shows:  .find 

line  TUG 

Reopen  the  definition  of  the  FIND  macro. 

You  Type:  .MAC/ FIND/  |  enter  I 

Screen  Shows:  .mac/FIND/ 

M: 

Show  that  the  macro  is  still  intact. 

You  Type:  {CTJDTjt »  [Wfm 

Screen  Shows:  "L» 

FIND 

S"TW0" 

Add  the  numeric  parameter  and  the  string  parameter  to  the 

macro's  header. 

You  Type:  c/find/find  #n  $str/  [enter] 

Screen  Shows:  c/find/find  #n  *str/ 

FIND   #N    $STR 

Move  to  the  second  line  of  the  macro. 
You  Type:  +  [mm] 

Screen  Shows:  + 

S"TN0" 
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Give  the  macro's  parameters  to  the  S  command.  Now  the  FIND 
macro  will  perform  the  same  function  as  the  S  command. 

You  Type:  c/"TW0"/  #N  $STR/  fgifflRl 

Screen  Shows:  c/"TWOH/  #N  $STR 

S    #N    $STR 

Close  the  macro's  definition. 

You  Type:  Q  I  enter  [ 

Screen  Shows:  E : 

Display  the  contents  of  the  edit  buffer.  

You  Type:  [cTrl~1[T1l»  I  enter  | 

Screen  Shows:  *L» 

LINE  DNE 

LINE  TWO 

LINE  THREE 

Use  the  FIND  macro  to  find  the  next  two  occurrences  of  LINE. 
YouType:  .FIND  2   /LINE/  [ENTER] 

Screen  Shows:  .find  2  /LINE/ 

LINE  ONE 

LINE  TWO 

Create  a  new  macro. 
You  Type: 
Screen  Shows: 


.MAC//  [  ENTER  ] 

.MAC// 

M: 


Define  the  macro  FIND_LINE,  which  performs  the  same  func- 
tion as  the  S  command  except  that  it  returns  the  edit  pointer  to 
the  head  of  the  line  after  finding  the  last  occurrence  of  STR. 
YouType:  dfind_line  #n  $str  CenterI 

Screen  Shows:  F I nd_l INE  #  N  JSTR 


You  Type: 

Screen  Shows: 

Turn  off  the  verify  mode. 
You  Type: 
Screen  Shows: 


DS    #N     SSTR  I  ENTER  [ 
S    #N    $STR 


V0 


ENTER 


Move  the  edit  pointer  to  the  first  character  of  the  current  line. 
You  Type:  -  0  I  enter  1 

Screen  Shows:  -0 
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Close  the  macro's  definition. 

You  Type:  q  |  enter  | 

Screen  Shows:  Q 

E: 

Display  the  contents  of  the  edit  buffer. 

You  Type:  fcTRniDL*  [Tnter] 

Screen  Shows:  *L* 

LINE  ONE 

LINE  TWO 

LINE  THREE 

Use  the  FIND-LI NE  macro  to  search  for  the  string  TWO. 
You  Type:  .  F I  ND_L  I NE/TWO/  fWERl 

Screen  Shows:  .  f  I  nd_l  i  n e / two / 

LINE    TWO 

Show  that  the  FINDJLINE  macro  left  the  edit  pointer  at  the 
head  of  the  line. 

You  Type:  l  [  enter  | 

Screen  Shows:  L 

LINE    TWO 

Create  a  new  macro. 

You  Type:  . mac / /  |  enter  I 

Screen  Shows:  .  m  a  c  /  / 

M: 
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Use  the  exclamation  point  (!)  command  to  comment  itself.  Type 
the  following: 

CONVERT_T0_tINES  *N  fENTERl 


!  This  is  a  comment  |  ENTER  | 

!  [ ENTER  | 

!  This  macro  converts  the  next  n  I  ENTER  I 


!  space  characters  to  new  line  [  ENTER | 
!  characters.  I  ENTER  I 


VB  !  Turn  verify  mode  off  | ENTER  I 


i 


ENTER 


!  to  prevent  intermediate  results  | ENTER  | 
!  from  being  displayed.  |  ENTER  ] 


I        !  Begin  loop  |  ENTER  | 

.SEARCH/  /  (Search  for  the  space  character.  [  ENTER  | 
Ml  !  Insert  empty  line  {new  line  character).  [  ENTER  | 

!  Back  up  one  line.  |  ENTER  | 


C/  //     !  Delete  the  next  space  character.  [ EMTER  ] 
L  *       !  Show  line,  move  past  it.  |  ENTER | 


1  'N      !  End  of  loop.  Repeat  #N  times,  j  ENTER  1 

Close  the  macro's  definition. 

You  Type:  Q  [  enter  1 

Screen  Shows;  o 

E: 

Display  the  contents  of  the  edit  buffer. 

You  Type:  rjTRT|[T|L*  [  enter  1 

Screen  Shows:  *L« 

LINE  DHE 
LINE  TWO 
LINE  THREE 

Convert  all  space  characters  to  new  line  characters. 

Note:  The  loop  stops  when  the  C  command  in  the  macro 

cannot  find  a  space  to  delete. 

You  Type:  . convert_to_lines   *  |  enter  | 

Screen  Shows:  ,convert_to_lines  * 

LINE 
LINE 
LINE 
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Display  the  contents  of  the  edit  buffer. 

You  Type:  rcTRTHTlL »  [mm 

Screen  Shows:  *L* 

LINE 

ONE 

LINE 

TWO 

LINE 

THREE 
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EDIT  newffle 


Edit  Quick  Reference  Summary 

EDIT  OS-9  loads  the  editor  and  starts  it  without 

creating  any  read  or  write  files.  Perform  text- 
file  operations  by  opening  files  after  the  editor 
is  running. 

OS-9  loads  the  editor  and  starts  it.  If  newfik 
does  not  exist,  Edit  creates  it  and  makes  it  the 
initial  write  file.  Although  this  command  does 
not  create  an  initial  read  file,  you  can  open 
read  files  after  starting  Edit. 

OS-9  loads  the  editor  and  starts  it,  making 
the  initial  read  file  oldfile.  The  editor  creates 
a  new  file  called  SCRATCH  as  the  initial 

write  file.  When  the  edit  session  is  complete, 
Edit  deletes  oldfile  and  renames  SCRATCH  to 
oldfile. 

EDIT  oldfile        OS-9  loads  the  editor  and  starts  it.  The  initial 

newfile  read  file  is  oldfile.  The  editor  creates  a  file 

called  newfile  as  the  initial  write  file. 


EDIT  oldfile 


Edit  Commands 
MACRO 


□ 


1  ENTER 


+  n 


-n 


+  0 


Executes  the  macro  specified  by  the  name  fol- 
lowing the  period  (.). 

Places  comments  inside  a  macro,  and  ignores 
the  remainder  of  the  command  line. 

Inserts  a  line  before  the  current  position  of  the 
edit  pointer. 

Moves  the  edit  pointer  to  the  next  line,  and 
displays  it. 

Moves  the  edit  pointer  forward  n  lines  and  dis- 
plays the  line. 

Moves  the  edit  pointer  backward  n  lines  and 
displays  the  line. 

Moves  the  edit  pointer  to  the  last  character  of 
the  line. 
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-0 

>a 
<n 


fcmpfTl  or  D  for 
external 

terminals 

/ 
[commands]  n 


An 


A0 

Bn 

Cn  strl  str2 
Dn 

En  str 

Gn 

In  str 

Kn 

Ln 


Moves  the  edit  pointer  to  the  first  character  of 
the  current  line  and  displays  it. 

Moves  the  edit  pointer  forward  re  characters. 

Moves  the  edit  pointer  backward  n  characters. 

Moves  the  edit  pointer  to  the  beginning  of  the 

text. 

Moves  the  edit  pointer  to  the  end  of  the  text. 

Repeats  the  sequence  of  commands  between 
the  two  brackets  n  times. 

Skips  to  the  end  of  the  innermost  loop  or 
macro  if  the  fail  flag  is  not  on. 

Sets  the  SEARCH/CHANGE  anchor  to  Col- 
umn n,  restricting  searches  and  changes  to 
those  strings  starting  in  Column  n.  This  com- 
mand remains  in  effect  for  the  current  com- 
mand line. 

Returns  the  anchor  to  the  normal  mode  of 
searching  so  that  strings  are  found  regardless 
of  the  column  in  which  they  start. 

Makes  buffer  n  the  primary  buffer. 

Changes  the  next  n  occurrences  of  strl  to  str2. 

Deletes  n  lines. 

Extends  (adds  the  string  to  the  end  of)  the 
next « lines. 

Gets  «  lines  from  the  secondary  buffer,  start- 
ing from  the  top.  Inserts  the  lines  before  the 
current  position  in  the  primary  buffer. 

Inserts  a  line  containing  n  copies  of  the  string 
before  the  current  position  of  the  edit  pointer. 

Kills  ft  characters  starting  at  the  current 
position  of  the  edit  pointer. 

Lists  (displays)  the  next  n  lines,  starting  at 
the  current  position  of  the  edit  pointer. 
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Mji  Changes  workspace  (memory)  size  to  n  bytes. 

Pn  Puts  (moves)  n  lines  from  the  position  of  the 

edit  pointer  in  the  primary  buffer  to  the  posi- 
tion of  the  edit  pointer  in  the  secondary  buffer. 

Q  Quits  editing  (and  terminates  editor).  If  you 

specified  a  file(s)  when  you  entered  Edit, 
Buffer  1  is  written  to  the  output  file.  The 
remainder  of  the  input  file  is  copied  to  the  out- 
put file.  All  files  are  closed. 

Rjj  Reads  n  lines  from  the  buffer's  input  file. 

Sn  str  Searches  for  the  next  n  occurrences  of  the 

string. 

Tn  Tabs  to  Column  n  of  the  present  line.  If  n  is 

greater  than  the  line  length,  Edit  extends  the 
line  with  space. 

U  Unextends  (truncates)  a  line  at  the  current 

position  of  the  edit  pointer. 

Vmode  Turns  the  verify  mode  on  or  off. 

Wn  Writes  n  lines  to  the  buffer's  output  file. 

Xn  Displays  n  lines  that  precede  the  edit  position. 

The  current  line  is  counted  as  the  first  line. 

Pseudo  Macros 

.CHANGE  n         Changes  n  occurrences  of  strl  to  str2. 
strl  str2 

.DEL  str  Deletes  the  macro  specified  by  str. 

■DIR  Displays  the  directory  of  buffers  and  macros. 

•EOB  Tests  for  the  end  of  the  buffer. 

.EOF  Tests  for  the  end  of  the  file. 

.EOL  Tests  for  the  end  of  the  line. 

•F  Exits  the  innermost  loop  or  macro  and  sets  the 

fail  flag. 

.LOAD  str  Loads  macros  from  the  path  specified  in  the 

string. 
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.MAC  str 

.NEOB 
.NEOL 
.NEW 


.NSTR  str 

.READ  str 
.S 


.SEARCH  n 

str 

.SAVE  strl 
str2 

.SHELL 

command  line 

.SIZE 


.STAR  n 
.STR  str 

.WRITE  str 

.ZERO  n 

[ 

] 


Opens  the  macro  specified  by  the  string  for 
definition.  If  you  give  an  empty  string,  Edit 
creates  a  new  macro. 

Tests  for  not  end  of  buffer. 

Tests  for  not  end  of  file. 

Writes  all  lines  up  to  the  current  line  to  the 
initial  output  file,  and  then  attempts  to  read 
an  equal  amount  of  text  from  the  initial  input 
file.  The  text  read-in  is  appended  to  the  end  of 
the  edit  buffer. 

Tests  to  see  if  string  does  not  match  the  char- 
acters at  the  current  position  of  the  edit 
pointer. 

Opens  an  OS-9  text  file  for  reading,  using 
string  as  the  pathlist. 

Exits  the  innermost  loop  or  macro  and  suc- 
ceeds (clears  the  fail  flag). 

Searches  for  n  occurrences  of  str. 


Saves  the  macros  specified  in  strl  on  the  file 
specified  by  the  pathlist  in  str2. 

Calls  OS-9  shell  to  execute  the  command  line. 


Displays  the  size  of  memory  used  and  the 
amount  of  memory  available  in  the  workspace. 

Tests  to  see  if  n  equals  asterisk  (infinity). 

Tests  to  see  if  string  matches  the  characters  at 
the  current  position  of  the  edit  pointer. 

Opens  an  OS-9  text  for  writing,  using  str  as  a 
pathlist. 

Tests  n  to  see  if  it  is  zero. 

Starts  at  a  macro  loop;  press  |  ctrl  |(T). 

Ends  at  a  macro  loop;  press  ]  ctrl  |[T|. 
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[-] 


Moves  edit  pointer  to  beginning  of  buffer; 
press  |  CTRL  1|T1. 


Editor  Error  Messages 


BAD  MACRO      You  did  not  begin  the  first  line  in  a  macro 
NAME  with  a  legal  name,  You  can  close  the  definition 

of  a  macro  after  you  give  it  a  legal  name. 


BAD 
NUMBER 

BAD  VAR 

NAME 

BRACKET 

MISMATCH 

BREAK 


DUPL 
MACRO 

END  OF 

FILE 

FILE 
CLOSED 


MACRO  IS 
OPEN 

MISSING 
DELIM 

NOT  FOUND 


You  have  entered  an  illegal  numeric  parame- 
ter, probably  a  number  greater  than  65,535. 

You  have  specified  an  illegal  variable  name, 
omitted  the  variable  name,  or  included  a  $  or 
#  character  in  the  commands  parameter  list. 

You  have  not  entered  brackets  in  pairs  or  the 
brackets  are  nested  too  deeply. 

You  pressed  |  ctrl  ifc")  or  I  ctrl  |[~o]  to  interrupt 
the  editor.  After  printing  the  error  message, 
the  editor  returns  to  command  entry  mode. 

You  attempted  to  close  a  macro  definition  with 
an  existing  macro  name.  Rename  the  macro 
before  trying  to  close  its  definition. 

You  are  at  the  end  of  the  edit  buffer. 


You  tried  to  write  to  a  file  that  is  not  open. 
Either  specify  a  write  file  when  starting  the 
editor  from  OS-9,  or  open  an  output  file  using 
the  .WRITE  pseudo  macro. 

You  must  close  the  macro  definition  before 
using  the  command. 

The  editor  could  not  find  a  matching  delimiter 
to  complete  the  string  you  specified.  "You  must 
put  the  entire  string  on  one  line. 

The  editor  cannot  find  the  specified  string  or 
macro. 
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UNDEFINED      You  used  a  variable  that  is  not  specified  in  the 
VAR  macro's  definition  parameter  list.  A  variable 

parameter  can  be  used  only  in  the  macro  in 

which  it  is  declared. 

WHAT  ??  The  editor  does  not  recognize  a  command.  You 

typed  a  command  that  does  not  exist  or  mis- 
spelled a  name. 

WORKSPACE      The  buffer  did  not  have  room  for  the  text  you 
FULL  want  to  insert.  Increase  the  workspace,  or 

remove  some  text. 
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OS-9  Error  Codes 


The  following  table  shows  OS-9  error  codes  in  hexadecimal  and 
decimal.  Error  codes  other  than  those  listed  are  generated  by 
programming  languages  or  user  programs. 


OS-9  Error  Codes 


Code 
HEX     DEC         Code  Meaning 


$01        001  UNCONDITIONAL  ABORT.  An  error  occurred 

from  which  OS-9  cannot  recover.  All  processes 
are  terminated. 

$02       002  KEYBOARD  ABORT.  You  pressed  [MmC]  to 

terminate  the  current  operation. 

$03       003  KEYBOARD   INTERRUPT.   You  pressed 

I  shift  ||  break  |  either  to  cause  the  current  opera- 
tion to  function  as  a  background  task  with  no 
video  display  or  to  cause  the  current  task  to 
terminate. 

$B7       183  ILLEGAL  WINDOW  TYPE.  You. tried  to 

define  a  text  type  window  for  graphics  or  used 
illegal  parameters. 

$B8       184  WINDOW  ALREADY  DEFINED.  You  tried  to 

create  a  window  that  is  already  established. 

$B9       185  FONT  NOT  FOUND.  You  tried  to  use  a  win- 

dow font  that  does  not  exist. 

$BA      186  STACK  OVERFLOW.  Your  process  (or  pro- 

cesses) requires  more  stack  space  than  is 
available  on  the  system. 

$BB       187  ILLEGAL  ARGUMENT.  You  have  used  an 

argument     with     a     command     that     is 

inappropriate. 

$BD       189  ILLEGAL  COORDINATES.  You  have  given 

coordinates  to  a  graphics  command  which  are 
outside  the  screen  boundaries. 
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Code 
HEX     DEC  Code  Meaning 


$BE       190  INTERNAL  INTEGRITY  CHECK.  System 

modules  or  data  are  changed  and  no  longer 
reliable. 

$BF       191  BUFFER  SIZE  IS  TOO  SMALL.  The  data  you 

assigned  to  a  buffer  is  larger  than  the  buffer. 

ICO       192  ILLEGAL  COMMAND.  You  have  issued  a 

command  in  a  form  unacceptable  to  OS-9. 

$C1       193  SCREEN  OR  WINDOW  TABLE  IS  FULL.  You 

do  not  have  enough  room  in  the  system  win- 
dow table  to  keep  track  of  any  more  windows 
or  screens. 

$C2       194  BAD/UNDEFINED  BUFFER  NUMBER.  You 

have  specified  an  illegal  or  undefined  buffer 
number. 

$C3       195  ILLEGAL  WINDOW  DEFINITION.  You  have 

tried  to  give  a  window  illegal  parameters. 

$C4       196  WINDOW  UNDEFINED.  You  have  tried  to 

access  a  window  that  you  have  not  yet  defined. 

$C8       200  PATH  TABLE  FULL.  OS-9  cannot  open  the 

file  because  the  system  path  table  is  full. 

$C9       201  ILLEGAL  PATH  NUMBER.  The  path  number 

is  too  large,  or  you  specified  a  non-existent 
path. 

$CA      202  INTERRUPT  POLLING  TABLE  FULL.  Your 

system  cannot  handle  an  interrupt  request, 
because  the  polling  table  does  not  have  room 
for  more  entries. 

$CB      203  ILLEGAL  MODE.  The  specified  device  cannot 

perform  the  indicated  input  or  output  function. 

$CC      204  DEVICE  TABLE  FULL.  The  device  table  does 

not  have  enough  room  for  another  device. 
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Code 
HEX     DEC         Code  Meaning 


$CD      205  ILLEGAL  MODULE  HEADER.  OS-9  cannot 

load  the  specified  module  because  its  sync 
code,  header  parity,  or  cyclic  redundancy  code 
is  incorrect. 

$CE      206  MODULE  DIRECTORY  FULL.  The  module 

directory  does  not  have  enough  room  for 
another  module  entry. 

$CF      207  MEMORY  FULL.  Process  address  space  is  full 

or  your  computer  does  not  have  sufficient  mem- 
ory to  perform  the  specified  task. 

$D0       208  ILLEGAL  SERVICE  REQUEST.  The  current 

program  has  issued  a  system  call  containing 
an  illegal  code  number. 

$D1       209  MODULE  BUSY.  Another  process  is  already 

/-^  using  a  non-shareable  module. 

$D2       210  BOUNDARY  ERROR.  OS-9  has  received  a 

memory  allocation  or  deallocation  request  that 
is  not  on  a  page  boundary. 

$D3       211  END  OF  FILE.  A  read  operation  has  encoun- 

tered an  end-of-file  character  and  has 
terminated. 

$D4       212  RETURNING  NON- ALLOCATED  MEMORY. 

The  current  operation  has  attempted  to  deallo- 
cate memory  not  previously  assigned. 

$D5       213  NON-EXISTING  SEGMENT.  The  file  struc- 

ture of  the  specified  device  is  damaged. 

$D6       214  NO  PERMISSION.  The  attributes  of  the  speci- 

fied file  or  device  do  not  permit  the  requested 
access. 

$D7       215  BAD  PATHNAME.  The  specified  pathlist  con- 

tains a  syntax  error,  for  instance  an  illegal 
character. 

$D8       216     '       PATH  NAME  NOT  FOUND.  The  system  can- 
not find  the  specified  pathlist. 
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Code 
HEX     DEC         Code  Meaning 


$D9       217  SEGMENT  LIST  FULL.  The  specified  file  is 

too  fragmented  for  further  expansion. 

$DA      218  FILE  ALREADY  EXISTS.  The  specified  file- 

name already  exists  in  the  specified  directory. 

$DD      219  ILLEGAL  BLOCK  ADDRESS.  The  file  struc- 

ture of  the  specified  device  is  damaged. 

$DC      220  PHONE  HANGUP  -  DATA  CARRIER  LOST. 

The  data  carrier  detect  is  lost  on  the  RS-232 
port. 

$DD      221  MODULE  NOT  FOUND.  The  system  received 

a  request  to  link  a  module  that  is  not  in  the 
specified  directory. 

$DF      223  SUICIDE  ATTEMPT.  The  current  operation 

has  attempted  to  return  to  the  memory  loca- 
tion of  the  stack. 

$E0       224  ILLEGAL  PROCESS  NUMBER.  The  specified 

process  does  not  exist. 

$E2       226  NO  CHILDREN.  The  system  has  issued  a 

wait  service  request  but  the  current  process 
has  no  dependent  process  to  execute. 

$E3       227  ILLEGAL  SWI  CODE.  The  system  received  a 

software  interrupt  code  that  is  less  than  1  or 
greater  than  3. 

$E4       228  PROCESS  ABORTED.  The  system  received  a 

signal  Code  2  to  terminate  the  current 
process. 

$E5       229  PROCESS  TABLE  FULL.  A  fork  request  can- 

not execute  because  the  process  table  has  no 
room  for  more  entries. 

$E6       230  ILLEGAL  PARAMETER  AREA.  A  fork  call 

has  passed  incorrect  high  and  low  bounds. 

$E7       231  KNOWN  MODULE.  The  specified  module  is 

for  internal  use  only. 
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Code 
HEX     DEC         Code  Meaning  

$E8       232  INCORRECT  MODULE  CRC.  The  cyclic 

redundancy  code  for  the  module  being 
accessed  is  bad. 

$E9       233  SIGNAL  ERROR.  The  receiving  process  has  a 

previous,  unprocessed  signal  pending. 

$EA      234  NON-EXISTENT  MODULE.  The  system  can- 

not locate  the  specified  module. 

$EB      235  BAD  NAME.  The  specified  device,  file,  or  mod- 

ule name  is  illegal. 

$EC      236  BAD  HEADER.  The  specified  module  header 

parity  is  incorrect. 

$ED      237  RAM  FULL.  No  free  system  random  access 

memory  is  available:  the  system  address  space 
is  full,  or  there  is  no  physical  memory  avail- 
able when  requested  by  the  operating  system 
in  the  system  state. 

$EE      238  UNKNOWN  PROCESS  ID.  The  specified  pro- 

cess ID  number  is  incorrect. 

$EF      239  NO  TASK  NUMBER  AVAILABLE.  All  avail- 

able task  numbers  are  in  use. 

Device  Driver  Errors 

I/O  device  drivers  generate  the  following  error  codes.  In  most 
cases,  the  codes  are  hardware-dependent.  Consult  your  device 
manual  for  more  details. 


Code 

HEX 

DEC 

Code  Meaning 

^        $F0 

240 

UNIT  ERROR.  The  specified  device  unit 
doesn't  exist. 

$F1 

241 

SECTOR  ERROR.  The  specified  sector  number 

is  out  of  range. 

$F2 

242 

WRITE  PROTECT.  The  specified  device  is 

write-protected. 
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Color  Computer  2  Compatibility 


Color  Computer  3  OS-9  Level  Two  provides  compatibility  with 
the  Color  Computer  2  and  OS-9  Level  One  by  letting  you  use  the 
video  display  in  the  Alphanumeric  mode  (including  Semigraphic 
box  graphics)  and  in  the  Graphics  mode,  lb  control  the  display, 
it  has  many  built-in  functions  that  you  activate  using  ASCII 
control  characters.  Any  program  written  in  a  language  using 
standard  output  statements  (such  as  PUT  in  BASIC)  can  use 
these  functions.  Color  Computer  BASIC09  has  a  Graphics  Inter- 
face Module  that  can  automatically  generate  most  of  these  codes 
using  BASIC09  RUN  statements. 

The  Color  Computer's  display  system  uses  a  separate  memory 
area  for  each  Display  mode.  Therefore,  operations  on  the  Alpha 
display  do  not  affect  the  Graphics  display  and  vice-versa.  You  can 
select  either  display  with  software  control.  (See  Getting  Started 
With  Extended  Color  BASIC  for  more  detailed  information.) 

The  system  interprets  8-bit  characters  sent  to  the  display 
according  to  their  numerical  values,  as  shown  in  this  chart: 

Character  Range  (Hex)      Mode/Function 

00  -  0E  Alpha — Cursor   and   screen 

control. 

OF  -  ID  Graphics — Drawing  and  screen 

control. 

IB  -  IF  Alpha — Escape  load  in  charac- 

ters for  high  resolution  graph- 
ics and  text. 

20  -  5F  Alpha — Uppercase  characters. 

60  -  7F  Alpha — Lowercase  characters. 

80  -  FF  Alpha — Semigraphic  patterns. 

The  device  driver  CC3IO  calls  a  subroutine  module  named 
VDGInt  to  handle  all  text  and  graphics  for  the  Color  Com- 
puter 2  compatibility  mode. 
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Alpha  Mode  Display 

The  Alpha  mode  is  the  standard  operational  mode.  Use  it  to  dis- 
play alphanumeric  characters  and  semigraphic  box  graphics.  Use 
it  also  to  simulate  the  operation  of  a  typical  computer  terminal 
with  functions  for  scrolling,  cursor  positioning,  clearing  the 
screen,  deleting  lines,  and  so  on. 

The  Alpha  mode  assumes  that  each  8-bit  code  the  system  sends 
to  the  display  is  an  ASCII  character.  If  the  high-order  bit  of  the 
code  is  clear,  the  system  displays  the  appropriate  alphanumeric 
character.  If  the  high-order  bit  is  set,  OS-9  generates  a  Semi- 
graphic  6  graphics  box.  See  Getting  Started  With  Extended  Color 
BASIC  for  an  explanation  of  semigraphic  functions. 

The  standard  32-column  Alpha  mode  display  is  handled  by  the 
I/O  subroutine  module  VDGInt.  CC3IO  calls  this  module 
(included  in  the  standard  boot  file)  to  process  all  text  and  semi- 
graphic  output. 

The  following  chart  provides  codes  for  screen  display  and  cursor 
control.  You  can  use  the  functions  from  the  OS-9  system  prompt 
by  typing  DISPLAY,  followed  by  the  appropriate  codes.  For 
instance,  to  clear  the  screen,  type: 


display    0c  |  ENTER  | 

To  position  the  cursor  at  column  16,  Line  5  and  display  the  word 
HELLO,  type: 

display   02    30    2S    48   4S    4c    4c    4f  |  ENTER  I 

You  can  also  use  the  following  codes  in  a  language,  such  as 
BASIC09.  To  do  so,  use  decimal  numbers  with  the  CHR$  func- 
tion, such  as: 

print    chr$C02);chr$(48>;chr$<37) ;chr$<72) 
;chr$C69);chr$<76);chr*C76);chr$C79> 

Using  Alpha  Mode  Controls  with  Windows 

The  control  functions  in  the  following  chart  also  function  prop- 
erly under  the  high  resolution  windowing  systems.  References  to 
"screen"  are  also  references  to  windows. 
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Alpha  Mode  Command  Codes 


Hex  Decimal 

Control   Control 
Code        Code 


Name/Function 


$01  01  HOME— Returns  the  cursor  to  the  upper  left 

corner  of  the.  screen. 

$02         02  CURSOR  XY— Moves  the  cursor  to  character 

X  of  line  Y,  To  arrive  at  the  values  for  X  and 
Y,  add  20  hexadecimal  to  the  location  where 
you  want  to  place  the  cursor.  For  example,  to 
position  the  cursor  at  Character  5  of  Line  10 
(hexadecimal  A),  do  these  calculations: 

5 
+  20 
=  25  hexadecimal 

OA 
+  20 
=  2A  hexadecimal 

The  two  coordinates  are  $25  and  $2A. 

$03         03  ERASE  LINE— Erases  all  characters  on  the 

line  occupied  by  the  cursor. 

$04         04  CLEAR  TO  END  OF  LINE— Erases  all 

characters  from  the  cursor  position  to  the 
end  of  the  line. 
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Hex  Decimal 

Control    Control 
Code        Code 


Name/Function 


$05  05  CURSOR  ON-OFF— Allows  alteration  of  the 

cursor  based  on  the  value  of  the  next 
character.  Codes  are  as  follow; 


Default 

Hex 

Dec 

Char 

Function 

Color 

$20 

32 

space 

Cursor  OFF 

$21 

33 

I 

Cursor  ON 

Blue 

$22 

34 

a 

Cursor  ON 

Black 

$23 

35 

# 

Cursor  ON 

Green 

$24 

36 

$ 

Cursor  ON 

Yellow 

$25 

37 

% 

Cursor  ON 

Blue 

$26 

38 

& 

Cursor  ON 

Red 

$27 

39 

i 

Cursor  ON 

Buff 

$28 

40 

( 

Cursor  ON 

Cyan 

$29 

41 

) 

Cursor  ON 

Magenta 

$2A 

42 

* 

Cursor  ON 

Orange 

$06 

06 

CURSOR 

RIGHT— Moves  the  cursor  to  the 

right 

one  character  position. 

$08 

08 

CURSOR  LEFT— Moves  the  cursor 
one  character  position. 

■  to  the  left 

$09 

09 

CURSOR  UP — Moves  the  cursor  up  one  line. 

$0A 

10 

CURSOR 

DOWN  \ 

[linefeed) — Moves  the 

$oc 

$0D 

$0E 


12 

13 
14 


cursor  down  one  line. 

CLEAR  SCREEN— Erases  the  entire  screen, 
and  homes  the  cursor  (positions  it  at  the 
upper  left  corner  of  the  screen), 

RETURN— Returns    the    cursor    to    the 

leftmost  character  on  the  line. 

DISPLAY  ALPHA— Switches  the  screen  from 

Graphic  mode  to  Alphanumeric  mode. 
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Graphics  Mode  Display 

Use  the  Graphics  mode  to  display  high-resolution  2-  or  4-color 
VDG  graphics.  The  Graphics  mode  includes  commands  to  set 
color,  plot  and  erase  individual  points,  draw  and  erase  lines, 
position  the  graphics  cursor,  and  draw  circles. 

You  must  execute  the  display  graphics  command  before  using 
any  other  Graphics  mode  command.  This  command  displays  the 
graphics  screen  and  sets  a  display  format  and  color. 

The  first  time  you  enter  the  display  graphics  command,  OS-9 
allocates  a  6144-byte  display  memory.  There  must  be  at  least 
that  much  contiguous  free  memory  available.  (You  can  use 
MFREE  to  check  free  memory.)  The  system  retains  the  display 
memory  until  you  give  the  end  graphics  command,  even  if  the 
program  that  initiated  the  Graphics  mode  finishes.  Always  use 
the  end  graphics  command  to  release  the  display  memory  when 
you  no  longer  need  the  Graphics  mode. 

Graphics  mode  supports  two  basic  formats.  The  2-color  format 
has  256  horizontal  by  192  vertical  points  (G6R  mode).  The  4- 
color  format  has  128  horizontal  by  192  vertical  points  (G6C 
mode).  Either  mode  provides  both  color  sets.  Regardless  of  the 
resolution  of  the  selected  format,  ail  Graphics  mode  commands 
use  a  256  by  192  point  coordinate  system.  The  X  and  Y  coordi- 
nates are  always  positive  numbers.  Point  0,0  is  the  lower  left  eor- 
ner  of  screen. 

Many  commands  use  an  invisible  graphics  cursor  to  reduce  the 
output  required  to  generate  graphics.  You  can  explicitly  set  this 
cursor  to  any  point  by  using  the  set  graphics  cursor  command. 
You  can  also  use  any  other  commands  that  include  x,y  coordi- 
nates (such  as  set  point)  to  move  the  graphics  cursor  to  the  speci- 
fied position. 

Any  graphics  function  that  draws  on  the  graphics  screen 
requires  that  the  VDGInt  module  is  loaded  into  memory  during 
the  system  boot. 

Graphics  Mode  Selection  Codes 

Code  Format 

00  256  x  192  two-color  graphics 

01  128  x  192  four-color  graphics 
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Color  Set  and  Foreground  Color  Selection  Codes 


2-Color  Format 

4-Color  Format 

Char 

Back- 

Fore- 

Back- 

Fore- 

ground 

ground 

ground 

ground 

00 

Black 

Black 

Green 

Green 

Color 

01 

Black 

Green 

Green 

Yellow 

Setl 

02 

Green 

Blue 

03 

Green 

Red 

04 

Black 

Black 

Buff 

Buff 

Color 

05 

Black 

Buff 

Buff 

Cyan 

Setl 

06 

Buff 

Magenta 

07 

Buff 

Orange 

08 

Black 

Black 

Color 

09 

Black 

Dark  Green 

Setl 

10 

Black 

Med.  Green 

11 

Black 

Light  Green 

12 

Black 

Black 

Color 

13 

Black 

Green 

Setl 

14 

Black 

Red 

15 

Black 

Buff 

Graphics  Mode  Control  Commands 


Hex  Decimal 

Control    Control 
Code        Code 


Name/Function 


$0F  15  DISPLAY  GRAPHICS— Switches  the  screen 

to  the  Graphics  mode.  Use  this  command 
before  any  other  graphics  commands.  The 
first  time  you  use  it,  the  system  assigns  a  6- 
kilobyte  display  buffer  for  graphics.  If  6K  of 
contiguous  memory  isn't  available,  OS-9  dis- 
plays an  error.  Follow  the  display  graphics 
command  with  two  characters  specifying  the 
Graphics  mode  and  color/color  set, 
respectively. 

$10  16  PRESET  SCREEN— Presets  the   entire 

screen  to  the  color  code  passed  by  the  next 
character. 
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Hex  Decimal 

Control   Control 
Code        Code 


Name/Function 


$11  17  SET  COLOR— Sets  the  foreground  color  (and 

color  set)  to  the  color  specified  by  the  next 
character  but  does  not  change  the  Graphics 
mode. 

$12  18  END  GRAPHICS— Disables  the  Graphics 

mode,  returns  the  6K  byte  graphics  memory 
area  to  OS-9  for  other  use,  and  switches  to 
Alpha  mode, 

$13  19  ERASE  GRAPHICS— Erases  all  points  by 

setting  them  to  the  background  color,  and 
positions  the  graphics  cursor  at  the  desired 
position. 

$14  20  HOME  GRAPHICS  CURSOR— Moves  the 

graphics  cursor  to  coordinates  0,0  (the  lower 
left  corner). 

$15  21  SET   GRAPHICS   CURSOR— Moves   the 

graphics  cursor  to  the  given  x,y  coordinates. 
For  x  and  y,  the  system  uses  the  binary 
value  of  the  two  characters  that  immediately 
follow. 

$16  22  DRAW  LINE— Draws  a  line  in  the  fore- 

ground color  from  the  graphics  cursor  posi- 
tion to  the  given  x,y  coordinates.  For  x  and  y, 
the  system  uses  the  binary  value  of  the  two 
characters  that  immediately  follow.  The 
graphics  cursor  moves  to  the  end  of  the  line. 

$17  23  ERASE  LINE— Operates  the  same  as  the 

draw  line  function,  except  that  OS-9  draws 
the  line  in  the  background  color,  thus  erasing 
the  line. 

$18         24  SET  POINT— Sets  the  pixel  at  point  x,y  to 

the  foreground  color.  For  x  and  y,  the  system 
uses  the  binary  values  of  the  two  characters 
that  immediately  follow.  The  graphics  cursor 
moves  to  the  point  set. 
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Hex  Decimal 

Control    Control 
Code        Code 


Name/Function 


$19         25  ERASE  POINT— Operates  the  same  as  the 

set  point  function,  except  that  OS-9  draws  the 
point  in  the  background  color,  thus  erasing 
the  point. 

$1A         26  DRAW  CIRCLE— Draws  a  circle  in  the  fore- 

ground color  using  the  graphics  cursor  as  the 
center  point  and  using  the  the  binary  value 
of  the  next  character  as  the  radius, 

$1C         28  ERASE  CIRCLE— Operates  the  same  as  the 

draw  circle  function,  except  that  OS-9  draws 
the  circle  in  the  background  color,  thus  eras- 
ing the  circle. 

$1D         29  FLOOD  FILL— paints  with  the  foreground 

color,  starting  at  the  graphics  cursor  position 
and  extending  over  adjacent  pixels  having  the 
same  color  as  the  pixel  under  the  graphics 
cursor. 

Note:  When  you  call  FILL  the  first  time,  it  requests  alloca- 
tion of  a  512-byte  stack  for  the  fill  routine.  The  system  does 
not  return  this  memory  until  you  terminate  graphics  with 
the  end  graphics  command. 

Note:  The  chart  uses  hexadecimal  codes  for  compatibility 
with  the  OS-9  DISPLAY  command. 


Display  Control  Codes  Summary 


1st  Byte 

Dec  Hex    2nd  Byte 


3rd  Byte         Function 


00  00 

01  01 

02  02 

03  03 


Column  +  32    Row + 32 


Null 

Home  alpha  cursor 
Position  alpha  cursor 
Erase  line 


B-8 


Color  Computer  2  Compatibility  I  B 


1st  Byte 

Dec  Hex 

2nd  Byte 

3rd  Byte 

Function 

04 

04 

Erase  to  End  of  line 

05 

05 

Cursor  Code 

Alter  Cursor 

06 

06 

Move  cursor  right 

07 

07 

Sound  terminal  bell 

08 

08 

Move  cursor  left 

09 

09 

Move  cursor  up 

10 

0A 

Move  cursor  down 

11 

OB 

Erase  to  End  of  Screen 

12 

OC 

Clear  screen 

13 

OD 

Carriage  return 

14 

OE 

Select  Alpha  mode 

15 

OF 

Mode 

Color  Code 

Select  Graphics  mode 

16 

10 

Color  Code 

Preset  screen 

17 

11 

Color  Code 

Select  color 

18 

12 

Quit  Graphics  mode 

19 

13 

Erase  screen 

20 

14 

Home  Graphics  cursor 

21 

15 

X  Coord 

Y  Coord 

Move  graphics  cursor 

22 

16 

X  Coord 

Y  Coord 

Draw  line  to  x/y 

23 

17 

X  Coord 

Y  Coord 

Erase  line  to  x/y 

24 

18 

X  Coord 

Y  Coord 

Set  point  at  x/y 

25 

19 

X  Coord 

Y  Coord 

Clear  point  at  x/y 

26 

1A 

Radius 

Draw  circle 

28 

1C 

Radius 

Erase  circle 

29 

ID 

Flood  Fill 

B-9 
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OS-9  Keyboard  Codes 


Key  Definitions  With  Hexadecimal  Values 

NORM 

SHFT 

CTRL 

NORM 

SHFT 

CTRL 

NORM 

SHFT 

CTRL 

0    30 

0 

30 

.. 

@  40 

60 

NUL00 

P  50 

p    70 

DLE  10 

1    31 

t 

21 

7C 

A    41 

a 

61 

SOH  01 

Q.   51 

q    71 

DC1  11 

2    32 

" 

22 

00 

B    42 

b 

62 

STX  02 

R   52 

r     72 

DC2  12 

3    33 

# 

23 

- 

7E 

C    43 

c 

63 

ETX  03 

S    53 

s     73 

DC3  13 

4    34 

$ 

24 

00 

D   44 

d 

64 

EOT  04 

T    54 

t     74 

DC4  14 

5    35 

% 

25 

00 

E    45 

e 

65 

EMD05 

U  55 

u    75 

NAK  15 

6    36 

& 

26 

00 

F  46 

f 

66 

ACK  06 

V    56 

v    76 

SYN  16 

7    37 

• 

27 

- 

5E 

G  47 

R 

67 

BEL  07 

W  57 

w  77 

ETB  17 

8    38 

i 

28 

1 

5B 

H  48 

h 

68 

BSP  08 

X    58 

x    78 

CAN  18 

9     39 

) 

29 

1 

5D 

I    49 

i 

69 

HT    09 

Y  59 

y   79 

EM    19 

:     3A 

4 

2A 

00 

J    4A 

i 

6A 

LF     0A 

Z    5A 

z    7A 

SUM1A 

;     3B 

+ 

2B 

00 

K  4B 

k 

6B 

VT     0B 

,     2C 

< 

3C 

{ 

7B 

L   4C 

1 

6C 

FF     0C 

-    2D 

= 

3D 

5F 

M  4D 

m 

6D 

DR     0D 

.     2B 

> 

3E 

! 

7D 

N  4E 

n 

6E 

CO     0E 

/     2F 

? 

3F 

\ 

5C 

O  4F 

0 

6F 

CI      OF 

Function  Keys 

NORM 

SHFT 

CTRL 

BREAK 

05 

03 

IB 

ENTER 

0D 

0D 

0D 

SPACE 

20 

20 

20 

+- 

08 

18 

10 

-► 

09 

19 

11 

+ 

0A 

1A 

12 

♦ 

oc 

1C 

13 

C-l 
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OS-9  Keyboard  Control 
Functions 

Key  Definitions  for  Special  Functions  and  Characters 


Key 

Combination 


Control  Function  or  Character 


tm 


I  CTRL  | 

I  BREAK  |  or  |  CTRL  ||  E 

|  CTRL  |ld 

1  CTRL  |  (_J 

( CTRL )  LJ 

1  CTRL  |  [#J 

1  CTRL  |  UJ 

[  CTRL  ||  BREAK  | 

l-H  or  I  CTRL  ||  H| 

|  SHIFT  )|"«-)  or 

1  CTRL  ||  X  | 

|  SHIFT  ]|_BREAK  J  Or 

1  CTRL  ||  C  | 

1  CTRL  ||  0  | 

f  CTRL  ||  1  I 

I  CTRL  ||  7  I 

I  CTRL  ||  8  | 

I  CTRL  ]|  9  | 

Alternate  key — Sets  the  high  order  bit  on  a 
character.  Press  |  alt|  char. 

Use  as  a  control  key. 

Stops  the  program  currently  executing. 

Generates  an  underscore  (_). 

Generates  a  left  brace  ({). 

Generates  a  right  brace  (}). 

Generates  a  tilde  (")  character. 

Generates  a  reverse  slash  (\). 

Generates  an  end-of-file  (EOF).  This 
sequence  is  the  same  as  pressing  |  ESC  |  on  a 
standard  terminal. 

Generates  a  backspace. 

Deletes  the  entire  current  line. 

Interrupts  the  video  display  of  a  running 
program.  This  sequence  reactivates  the 
shell  and  then  runs  the  program  as  a  back- 
ground task. 

Upper-zlowercase  shift  lock  function. 

Generates  a  vertical  bar  (|)  in  reverse  video. 

Generates  an  up  arrow  or  caret  ("). 

Generates  a  left  bracket  ([). 

Generates  a  right  bracket  (]). 
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Key 
Combination  Control  Function  or  Character 


[  CTRL  II  A  1 

1  CTRL  II  D  I 

|  CTRL  ||  W  | 

Repeats  the  previous  command  line. 
Redisplays  the  command  line. 

Temporarily  halts  output  to  the  screen. 
Press  any  key  to  resume  output. 
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Code 
HEX     DEC         Code  Meaning 


$F3       243  CRC  ERROR.  A  cyclic  redundancy  code  error 

occurred  on  a  read  or  write  verify. 

$F4       244  READ  ERROR.  A  data  transfer  error  occurred 

during  a  disk  read  operation,  or  there  is  a 
SCF  (terminal)  input  buffer  overrun. 

$F5       245  WRITE  ERROR.  An  error  occurred  during  a 

write  operation. 

$F6       246  NOT  READY.  The  device  specified  has  a  not 

ready  status. 

$F7       247  SEEK  ERROR.  The  system  attempted  a  seek 

operation  on  a  non-existent  sector. 

$F8       248  MEDIA  FULL.  The  specified  media  has  insuf- 

ficient free  space  for  the  operation. 

$F9       249  WRONG  TYPE.  An  attempt  is  made  to  read 

incompatible  media  (for  instance  an  attempt  to 
read  double-side  disk  on  single-side  drive). 

$FA       250  DEVICE  BUSY.  A  non-shareable  device  is  in 

use. 

$FB      251  DISK  ID  CHANGE.  You  changed  diskettes 

when  one  or  more  files  are  open. 

$FC      252  RECORD  IS  LOCKED-OUT.  Another  process 

is  accessing  the  requested  record. 

$FD      253  NON-SHARABLE  FILE  BUSY.  Another  pro- 

cess is  accessing  the  requested  file. 


A-6 


Index 


ACIAPAK    5-6,5-7,6-90 
active  state    4-2 
address    2-4 

memory    4-5 
allocate  memory  for  devices 

6-55 
alpha  mode    B-2 

select    B-9 
alphanumeric  mode    B-l 
ampersand  separator    3-6 
append  files    6-68 
application  program    1-3 
arglist    6-2 
ASCII    2-5 

control  characters    B-l 

convert    6-38 
ASM    3-2 
asterisk,  editor    7-3 
ATTR    2-10,  6-5 
attribute    2-5,  2-8,  2-10,  6-5 
auto-answer  modem    6-89, 
6-102 

background 

color    B-6 

process    3-7 

task    4-1 

screen    5-2 
backspace    6-87 

character    6-88,  6-100, 
6-101 

editor    7-2 

over  line    6-87,  6-100 
BACKUP    5-4,6-7 
backup  a  directory    6-39 
BASIC09    2-5,  2-6,  3-13,  B-l 
baud  rate    5-4,  5-5,  5-6,  6-90, 

6-92,  6-103 
begin  a  window    6-97 
bell 

character    6-88,  6-101 

sound     B-9 


bit    2-1 

stop    5-5,  5-6 

user    2-11 
bitmap    2-5 
block 

number    4-5 

devices    1-2 
bootstrap    5-1 

file    5-2 
box  graphics    B-2 
brackets    6-3 
buffer    3-7,7-2 

edit    7-1 

secondary    7-1 

text    7-1 
BUILD    2-6,3-10,6-10 
built-in  commands    3-1,  3-11 
byte    2-1 

carriage  return    B-9 
CC3Disk    5-1 
CC3Go    5-2 
CC3IO    5-1,  B-l 

chaining  programs    6-44 

change 

attributes    2-10,  2-11 
directory    6-12,  6-85, 

6-78 
file  name    6-78 
priority    3-12,  6-82 
system  parameters    6-87 

character 

ASCII    2-5 
delete    6-101 
devices    1-2 
backspace    6-88,  6-100, 

6-101 
bell    6-88,6-101 
delete  line    6-88,  6-101 
dup    6-90,6-102 
end-of-file    6-89,6-101 
end-of-record    6-88,  6-101 
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character  (cont'd) 

lowercase    B-l 

pause    6-90,  6-103 

quit    6-90,6-103 

reprint    6-89,  6-102 

terminate    6-90,  6-103 

uppercase    B-l 
CHD    3-11,6-12 
check  disk  structure    6-25 
child  process    3-6,  4-2 
CHX    3-11,6-12 
circle 

draw    B-8 

erase    B-8,  B-9 
clear 

screen    B-4 

to  end-of-line    B-3 
clock    5-2 
cluster    2-4,  2-5 
CMDS  directory    5-1,  5-3,  5-4 
CMP    6-14 
COBBLER    6-16 
code 

alpha  mode  control    B-3 

cursor    B-4 

object    2-7 

position-independent    4-8 

re-entrant    4-6 
color 

background    B-6 

foreground    B-6,  B-7 

select    B-9 

set,  graphics    B-6 
combine  files    6-68 
command 

grouping    3-2,  3-9 

help    6-51 

interpreter    6-84 

line    3-1,  3-2 

parameters,  editor    7-3 

separator    3-1,  3-5 

summary,  editor    7-55 
command  codes 

alpha  mode    B-3 

graphics    B-6 


commandname    6-2 
commands 

ASM    3-2 

ATTR    2-10,2-11,6-5 
BACKUP    5-4,6-7 
BUILD    2-6,3-10,6-10 
built-in    3-11 
CHD    3-11,6-12 
CHX    3-11,6-12 
CMP    6-14 
COBBLER    6-16 
CONFIG    5-2,5-3,5-4, 

6-18 
COPY    2-3,3-6,4-8,6-22 
DATE    6-24 
DCHECK    6-25 
DEINIZ    6-30 
DEL    6-31 
DELDIR    2-3,  6-33 
DIR    2-6,  2-9,  6-35 
DISPLAY     6-38 
DSAVE    6-39 
DUMP    2-8 
ECHO    6-42 
edit  macro    7-28 
editor    7-2 
ERROR    5-2,6-43 
EX    3-11,6-44 
FORMAT    6-46 
FREE    6-49 
GET    2-6 
HELP    6-51 
i    3-11 

IDENT    3-3,  6-52 
INK    6-55 
KILL    3-12,  6-56 
LINK    6-58 
LIST    2-3,2-5,2-8,3-4, 

6-59 
LOAD    4-7,6-61 
MAKDIR    2-3,2-11, 

6-63 
MDIR    6-64 
MERGE    6-68 
MFREE    6-69 


Index 


commands  (cont'd) 

OS9GEN    5-2,5-3,6-70 

p    3-12 

PROCS    3-7,4-2,6-74 

PUT    2-6 

PWD    6-76 

PXD    6-76 

RENAME     6-78 

RUNB    3-13 

SEEK     2-6 

SETIME    5-3,6-80 

SETPR    3-12,6-82 

SHELL    3-6,  6-84 

t    3-12 

TMODE    6-87 

TUNEPORT    6-92 

UNLINK     4-7,4-8,6-94 

w    3-12 

WCREATE    6-97 

x    3-12 

XMODE    5-4,5-5,5-7, 
6-100 
comment,  in  a  program     3-12 
compare  files    6-14 
concurrent 

execution    3-5, 6-85 

mode    3-10 

process    3-9 

task    4-1 
CONFIG    5-2,  5-3,  5-4,  6-18 
control 

characters,  ASCII    B-l 

keys,  editor    7-2 
convert  to  ASCII     6-38 
COPY    2-3,3-6,4-8,6-22 
copy 

a  directory     6-39 

diskettes     6-7 
CPU    4-1 

priority    6-82 
CRC    2-7 
create 

a  directory    6-63 

a  file    6-10 

OS9Boot    6-16,6-70 


create  (cont'd) 

process    3-6 

system  diskette    5-3,  5-4, 
6-16,  6-18,  6-70 
current 

directory    4-4,  6-12 

processes    6-74 
cursor 

on/off    B-4 

codes    B-4 

control    B-l,  B-3 

graphics    B-5,  B-7 

home    B-3 

move    B-4,  B-9 
cyclic  redundancy  checksum 
2-7 

data  format    2-1 
data  output,  halt    7-3 
data 

redirect    3-4 

input/output    1-2 

passing    4-4 

process    2-1 

sending    2-1 

transfer    2-1 
DATE    6-24 
date    2-5 

set    6-80 
day     6-2 
DCHECK    6-25 
deallocate  a  device    6-30 
DEINIZ    6-30 
DEL    6-31 
delay,  not  ready    5-6 
DELDIR    2-3,6-33 
delete 

a  character    6-101 

a  directory    6-33 

aline    7-3 

a  memory  module    4-7, 
6-94 

files    6-31 

line  character    6-88, 
6-101 
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delete  (cont'd) 

lines,  editor    7-10 
descriptor 

device    1-2 

file    2-3 
detach  a  device    6-30 
device 

allocate  memory    6-55 

block-oriented    1-2 

character     1-2 

deallocate    6-30 

descriptor    1-2,  5-1 

driver     1-2,  2-1,  5-1 

driver  initialization 
6-55 

name    2-12, 2-13 

window    2-12  -  2-13 
devname    6-2 
DIR     2-6,  2-9,  6-35 
directory    2-2,  2-3 

attribute    2-8 

change    6-12,  6-85 

change  name    6-78 

CMDS    5-1,5-3,5-4 

copy    6-39 

create    6-63 

current    4-4,  6-12 

delete    6-33 

list    6-35 

module    4-6 

ownership    2-8 

SYS    5-1,5-4 

view    6-76 

working    6-12 
dirname    6-2 
disable  echo    6-88,  6-101 
disk 

cluster    2-4 

file    2-3,2-4 

I/O    3-8 

initialization    6-46 

names     2-12 

ownership    2-8 

sector    2-4 

structure,  check    6-25 


disk  (confd) 

raw  I/O    3-8 

unused  sectors    6-49 
diskette 

copy    6-7 

density    2-5 

tracks    2-5 

system    2-2 
DISPLAY    6-38 
display 

a  directory    6-35 

current  processes    6-74 

date  and  time    6-24 

error  message    6-43 

execution  directory    6-76 

file  contents    6-59 

free  memory    6-69 

graphics    B-6 

help    6-51 

memory  module  names 
6-64 

messages    6-42 

on  next  line    7-2 

text,  editor    7-6 

unused  disk  sectors    6-49 

working  directory    6-76 
double  density    2-5 
draw 

a  circle     B-8 

a  line    B-7,  B-9 
drivers,  device     1-2 
DSAVE    6-39 
DUMP    2-8 

dup  character    6-90,  6-102 
duplicate 

last  line    6-90 

line    6-102 

ECHO    6-42 
echo    6-86 

enable/disable    6-88, 
6-101 
edit 

buffer    7-1 

commands,  EDIT    7-5 


Index 


edit  (cont'd) 

pointer    7-1,  7-2,  7-7 
^.  EDIT,  editor    7-5 

editor    7-1 

backspace    7-2 
command  summary 

7-55 
command  syntax      7-4 
commands    7-2 
control  keys    7-2 
delete  lines    7-10 
error  messages    7-59 
getting  started    7-4 
insert  lines    7-10 
interrupt    7-3 
numeric  parameters    7-3 
quick  reference    7-55 
searching    7-13 
substituting    7-13 
terminate    7-2 
_^  text  file  operations    7-18 

using  the  asterisk    7-3 

ellipsis    6-3 

enable  echo    6-88,  6-101 

end  graphics    B-7 

end-of-file 

terminate    7-2 
character    6-89,  6-101 

end-of-line 

clearing    B-3 
erase     B-9 

end-of-record  character    6-88, 
6-101 

erase 

a  circle    B-8,  B-9 
a  line    B-9 
graphics    B-7 
line    B-3,  B-7,  B-8 
point    B-8 
'  to  end-of-line    B-9 

Errmsg    5-2 

ERROR    5-2,6-43 

error    3-12,  6-86 

message  file     5-2 
messages,  editor    7-59 


error  (cont'd) 

output    6-85 

path    3-4 
establish  a  directory     6-63 
EX    3-11,6-44 
exclamation  mark  separator 

3-8 
execute 

a  program    6-84 

permission    2-9,  2-10 
execution 

concurrent    3-5,  6-85 

modifier    3-1,  3-3 

sequential    3-5,  3-6,  6-85 

fields    2-6 
file    2-2-2-4 

attribute    2-8 

change  name    6-78 

compare    6-14 

copy    6-22 

create    6-10 

delete    6-31 

descriptor    2-3 

descriptor  sector    2-5 

display  contents    6-59 

load  in  memory     6-61 

merge     6-68 

manager    5-1 

OS9Boot    5-4 

ownership    2-8 

pointer    2-4 

procedure    2-6,  3-10, 
3-11 

random  access    2-6 

security    2-8 

shareable    2-8 

size    2-5 

Startup    2-6,  5-1,  5-3, 
5-4 

text    2-5 
filename    2-3,  6-2 
fill  portion  of  screen     B-8 
flood  fill     B-8,  B-9 
floppy  disk  names    2-12 
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fonts    5-2 

foreground  color    B-6,  B-7 

fork    3-7,4-6 

request    4-3 
FORMAT    6-46 

FREE    6-49 

generate  messages    6-42 
GET    2-6 

getting  started,  editor    7-4 
graphic  window  fonts    5-2 
graphics    B-l 

color  set    B-6 

command  codes    B-6 

cursor    B-5,  B-7 

mode,  select    B-9 

end    B-7 

erase    B-7 

medium  resolution    B-5 

VDG    B-5 
group     2-7 
grouping,  commands    3-9 

halt  data  output    7-3 
hardware    1-2 
header 

information    6-52 

module    2-7,3-3,4-7 
HELP    6-51 
hex    6-2 
hexadecimal  code  display 

6-38 
home 

alpha  cursor     B-8 

cursor    B-3 
hours    6-2 

I-code    3-13 
I/O 

paths    3-4 

transfers    3-8 

raw     3-8 
ID,  process    4-4 
IDENT    3-3,  6-52 
images,  pointer    5-2 


immortal 

process    6-85 

shell    3-11 
INIT    5-1 
initialize 

a  disk    6-46 

a  window    6-97 
INEZ    6-55 
input    2-1 

lines    3-12 

path    3-4 

redirect    6-85 

standard    4-4 
insert  lines,  editor    7-10 
interpreter,  commands    6-84 
interprocess  communication 

3-7 
interrupt  editor    7-3 
IOMAN    1-2,  1-3,  5-1 

kernel    1-1,  1-2 
keyboard    1-1 
keyword    3-1  -  3-3 
KILL    6-56 

kill    3-12 

a  directory    6-33,  6-33 
files    6-31 

length 

of  video  page    6-88 
word    5-5,  5-6,  6-90, 
6-102 

line 

backspace    6-87,  6-100 
delete,  editor    7-3 
draw    B-7,  B-9 
duplicate    6-90 
duplication    6-102 
erase    B-3,  B-7,  B-8,  B-9 
syntax    6-1 

linefeed    6-88,6-101 

lines,  command    3-1 

LINK    6-58 

LIST    2-3,  2-5,  2-8,  3-4,  6-59 


Index 


list 

a  directory    6-35 
/=—■  current  p-ocesses    6-74 

memory  module  names 
6-64 

segment    2-5 

with  program  files     2-8 
LOAD    4-7,  4-7,  6-61 
lock  a  module    6-58 
lockout    2-11 
logical  sector    2-3,  2-4 
lowercase    6-87,  6-100 

characters    B-l 

machine  language    3-12 

macro  text  editor    7-1 

macros,  edit    7-25 

MAKDIR    2-11,2-3,6-63 

management,  memory    4-5 

manager 
^^-^  pipe    1-2 

random  block     1-2 

mark  space    6-89,  6-102 

MDIR    6-64 

MDMkill    5-6,5-7 

medium  resolution  graphics 
B-5 

memory 

address    4-5 
allocation    3-1 
display  free    6-69 
load  a  file  into    6-61 
management    1-1, 4-5 
size  modifier    3-3 

memory  modules 
lock    6-58 
unlink     6-94 
deleting    4-7 
display  names    6-64 
^      MERGE    6-68 

messages  with  ECHO    6-42 

messages,  error    6-43 

MFREE    6-69 

minutes    6-2 


MMU    4-5 
mode,  alpha    B-2 
mode 

alphanumeric    B-l 

concurrent    3-10 

semigraphic    B-l 
modem     1-1,  5-6,  5-7 

auto-answer    6-102 

name    2-12 
modifier    3-1  -  3-3 

execution    3-1,  3-3 

memory  size    3-3 

redirection    3-5 
modname    6-2 
MODPAK    5-7 
module    1-3 

deleting  memory    4-7 

directory    4-6 

header    2-7,3-3,4-7 

header  information    6-52 

loading     4-7 

lock  in  memory    6-58 

primary    4-3 

program    2-7 

unlink    4-8 
month    6-2 

move  cursor    B-3,  B-4,  B-9 
multiprogramming    4-1 
multitasking    1-1 

name 

device    2-12,  2-13 

modem     2-12 

printer     2-12 

program    3-3 

terminal    2-12 
next  line,  display    7-2 
not  ready  delay    5-6 
notations,  syntax    6-1 
null  count    6-88,6-101 
number 

priority    3-12 

user    2-8,  4-4 
numeric  parameters,  editor 
7-3 
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object  code    2-7 
operating  system    1-3 
opts    6-2 
OS9Boot    5-1,5-4 

create    6-16,  6-70 
OS9Gen    5-2,5-3,6-70 
OS9p2    5-1 
output    2-1 

error    6-85 

path    3-4,  4-4 

redirect    3-11,6-85 
owner    2-5,  2-8 
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Chapter  1 

Looking  at  the  Basics 


BASIC09  is  a  computer  language  created  for  use  with  the  OS-9 
operating  system.  Along  with  standard  BASIC  language  state- 
ments and  functions,  it  includes  the  most  useful  elements  of  the 
PASCAL  computer  language. 

In  brief,  BASIC09's  advantages  are: 


Past  execution  speed 


Full  feature  editing 


Modular 
programming 

functions 


Interfacing  to  OS-9 


Structured 
programming 


BASIC09  compiles  procedure  lines  as 
you  enter  them.  When  you  finish  a 
procedure,  you  can  compile  it  further. 
The  result?  Procedures  that  execute 
nearly  as  fast  as  machine  language. 

The  text  editor  features  automatic  line 
formatting,  search,  search  and  change, 
global  search,  global  search  and 
change,  line  renumbering,  and  much 
more.  You  can  move  in  and  out  of  the 
editor  quickly  and  easily. 

You  can  write  small,  easy-to-under- 
stand  procedures,  then  chain  them  to 
create  sophisticated  programs.  You  can 
call  one  procedure  from  another, 
regardless  of  whether  the  called  proce- 
dure is  in  memory  or  on  disk. 

Both  you  and  your  procedures  can 
take  advantage  of  almost  any  OS-9 
function  from  within  BASIC,  including 
the  execution  of  disk  management 
commands  and  application  programs. 

You  can  structure  procedures  more 
efficiently  and  clearly  by  taking  advan- 
tage of  a  variety  of  loop  commands, 
optional  line  numbering,  and 
BASIC09's  ability  to  call  modules 
written  in  other  computer  languages. 
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Memory  saving 
features 


Complex  data 

structures 


Sophisticated 
graphics 


High  speed, 
precision  math 


Simple  and  fast 
debugging 


Strings  can  be  any  length.  For  each 
operation,  you  can  select  the  most  effi- 
cient of  five  available  data  types.  Com- 
piled procedures  use  less  space.  You 
can  save  several  procedures  into  one 
file. 

Combine  any  type  of  data  into  a  single 
dimensioned  data  structure  that  you 
can  move,  store,  and  assign  easily  and 
quickly. 

BASIC09  has  three  levels  of  graphics. 
The  high  resolution  graphics  and  text 

capabilities  feature  more  than  50 
functions. 

BASIC09  has  a  full  range  of  fast  and 
accurate  math  and  transcendental 
capabilities  including  powers,  roots, 
trigonometry,  logic,  and  Boolean 
functions. 

BASIC09  provides  superior  debugging 
functions.  It  checks  syntax  as  you 
enter  lines.  It  points  to  the  location  of 
your  errors  and  tells  you  what  they 
are.  "You  can  stop  programs,  enter  the 
debugger,  then  continue  execution. 
Execution  errors  automatically  put  you 
in  a  debugging  mode  where  you  can 
examine  values,  and  step  and  trace 
your  way  through  faulty  procedures. 


Using  BASIC09 

Before  anything  else,  make  a  backup  copy  of  your  BASIC09/ 
CONFIG  diskette.  You  can  do  this  using  the  BACKUP  command. 
If  you  are  not  familiar  with  BACKUP,  see  Chapter  3  of  Getting 
Started  With  OS-9. 

To  use  BASIC09,  boot  your  computer  as  described  in  Getting 
Started  With  OS-9.  Replace  the  system  diskette  in  Drive  /DO 
with  the  BASIC09/CONFIG  backup  diskette  and  type: 


basic09  [  ENTER  1 
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After  a  short  pause,  during  which  OS-9  loads  BASIC09  from  the 
diskette,  the  screen  displays  the  copyright  and  a  new  prompt, 
like  this: 

BASIC09 

RS  VERSION  01  .00.  01 

COPYRIGHT  1980  BY  MOTOROLA  INC. 

AND  MICROWARE  SYSTEMS  CORP. 

REPRODUCED  UNDER  LICENSE 

TO  TANDY  CORP. 

ALL  RIGHTS  RESERVED 

Bnaic09 

Ready 

B: 

The  B:  indicates  that  your  computer  is  in  the  BASIC09  command 
mode.  From  the  command  mode,  you  can  issue  instructions  to 
the  system  executive  to  manipulate  procedures  (programs). 

Requesting  More  Memory 

Unless  you  specify  otherwise,  BASIC09  automatically  sets  aside 
8192  bytes  of  memory  as  a  workspace  into  which  you  can  type  or 
load  procedures.  BASIC09  reserves  approximately  1200  bytes  of 
the  workspace  for  internal  use,  leaving  you  with  6992  bytes  for 
workspace. 

There  are  two  ways  to  set  aside  more  memory  for  BASIC09 
operations: 

•  You  can  reserve  extra  memory  when  you  first  enter 
BASIC09  by  using  the  OS-9  memory  size  option.  For 
instance,  to  reserve  18,176  bytes,  enter  this  command  to 
initialize  BASIC09: 


basic09   #18k  [  ENTER  I 


You  can  also  request  additional  memory  after  loading 
BASIC09.  At  the  command  prompt,  B : ,  type: 


mem    18000  I  ENTER  | 

This  tells  BASIC09  to  set  aside  a  total  of  18,000  bytes  of 
memory,  if  they  are  available. 
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In  both  cases,  because  BASIC09  rounds  the  amount  you  request 
to  the  next  multiple  of  256,  the  actual  reserved  memory  is  18176 
bytes. 

Note:  If  your  system  does  not  have  enough  free  memory  to 
reserve  the  amount  you  specify,  the  workspace  size  does  not 
change. 

You  can  also  use  the  MEM  command  to  reduce  memory.  How- 
ever, BASIC09  does  not  reduce  the  size  of  the  workspace  if  doing 
so  destroys  resident  procedures. 

Writing  Procedures 

BASIC09  is  a  modular  programming  language.  Several  proce- 
dures can  occupy  memory  at  the  same  time.  Each  procedure  per- 
forms a  particular  function  but  can  also  interact  with  others  to 
form  a  sophisticated  program. 

To  create  or  change  procedures,  enter  the  edit  mode  by  typing 
either  edit  I  enter  I  or  QQ  [  enter  I  at  the  B;  prompt.  From  now  on, 
when  directing  you  to  enter  the  edit  mode,  this  manual  uses  the 
easier  to  type  QQ- command. 

Each  time  you  type  a  procedure  line  and  press  I  enter  I,  the  editor 
checks  for  common  errors.  This  automatic  checking  lets  you 
catch  mistakes  before  you  run  the  program,  saving  you  testing 
and  rewriting  time.  You  can  even  let  the  automatic  checking 
help  you  learn  the  rules  of  BASIC09.  If  you  are  not  sure  about  a 
syntax,  go  ahead  and  type  it  the  way  you  think  is  correct.  If  you 
guess  wrong,  BASIC09  shows  where  the  error  is  and  displays  a 
message  to  tell  what  is  wrong. 

BASIC09's  use  of  modules  lets  you  divide  large  and  complex  proj- 
ects into  smaller,  easily  manageable  sections.  Not  only  are  the 
smaller  procedures  easier  to  write  and  understand,  they  are  also 
easier  to  test.  As  well,  because  BASIC09  lets  you  call  procedures 
that  are  outside  the  workspace  (the  computer's  memory  where 
you  write  and  edit  procedures),  you  can  accumulate  libraries  of 
procedures  to  incorporate  into  future  programs. 

You  can  work  on  a  program's  procedures  either  individually  or 
as  a  group.  For  example,  to  work  on  the  procedures  as  a  group, 
save  your  workspace  procedures  into  a  single  disk  file.  When  you 
subsequently  load  the  file,  BASIC09  automatically  loads  all  of 
the  procedures. 
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Modules  of  Other  Languages 

BASIC09  can  incorporate  procedures  from  other  languages,  such 
as  Pascal,  C,  or  assembly  language.  Several  users  can  then  share 
the  procedures. 

Executing  Procedures 

"fou  execute  or  run  programs  from  the  command  mode.  When 
you  enter  a  procedure,  BASIC09  compiles  it.  This  means  that  the 
procedure  is  ready  for  execution  as  soon  as  you  exit  the  edit 
mode.  For  instance,  if  you  create  a  program  named  Greeting, 
you  can  execute  it  by  typing  from  the  command  mode: 


run    greet  i  ng  (ENTER} 

Leaving  BASIC09 

There  are  two  ways  you  can  exit  from  BASIC09: 
•  At  the  B :  prompt,  type: 


bye  [  ENTER  ] 

•  Or,  at  the  B :  prompt,  press  j  ctrl  j|  break]. 

When  you  use  either  method,  the  OS-9  prompt  appears  immedi- 
ately indicating  that  the  operating  system  is  waiting  for  a 
command. 

Note:  When  you  exit  BASIC09,  you  lose  all  procedures 
residing  in  the  workspace.  Be  sure  to  save  them  on  disk 
before  leaving  BASIC09. 

The  Keyboard  and  BASIC09 

You  can  use  some  keys  and  key  sequences  to  produce  special 
characters  and  to  accomplish  special  BASIC09  functions.  Tfou  ini- 
tiate a  key  sequence  by  pressing  one  key  and  holding  it  down 
while  pressing  a  second  key.  The  following  list  summarizes  your 
keyboard's  special  functions: 
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[ALT] 


CTRLl 


BREAK    Or 


CTRL    E 


i  ctrl  inr 


retRnLJ 


rcTRnrr 


(CTRLl 


rctHLir*i 


rcTRLirr 


I  CTRL  II  BREAK  I 


SHIFT     BREAK] 


I  CLEAR 


I  SHIFT  II  CLEAR 


I  SHIFT  | 


or 


fCtRLlfXl 

(CTRDlXt 

fCTRLim 

rcTRTKTl 


reTRLim 


Produces  graphic  characters.  Press  ]  alt  |  char 
where  char  is  a  keyboard  character), 

A  control  key  that  you  use  with  other  keys. 
(See  below.) 

Stops  the  current  program  execution  and 
returns  to  the  B:  prompt  in  BASIC09's  com- 
mand mode. 

Moves  the  cursor  back  one  space. 


Produces  an  underscore  character. 

Produces  a  left  brace  (<). 

Produces  a  right  brace  (>). 

Produces  a  tilde  (~). 

Produces  a  backslash  (\). 

Performs  an  ESCAPE  function  and  sends  an 
end-of-file  message  to  a  program  receiving 
keyboard  input.  To  be  recognized,  fCTRL~||  break! 
must  be  the  first  thing  typed  on  a  line. 

Stops  execution  of  a  program  and  causes 
BASIC09  to  enter  the  Debug  mode. 

Displays  the  next  window. 

Displays  the  previous  window. 

Deletes  the  current  line. 

Activates  or  deactivates  the  shift  lock  function. 
Produces  a  vertical  bar  ( | ). 
Produces  an  up  arrow  (♦). 
Produces  a  left  bracket  (C). 
Produces  a  right  bracket  0). 
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["ctrTHD  Redisplays  the  last  line  typed,  and  positions 

the  cursor  at  the  end  of  the  line,  but  does  not 
process  the  line.  Press  1  enter  j  to  process  the 
line,  or  edit  the  line  by  backspacing.  If  you 
edit,  press  I  ctrl  ||~a~|  again  to  display  the  edited 
line. 

[  ctrl  ||~o~l  Redisplays  the  current  command  line. 

I  ctrl  Ifwl  Temporarily  halts  video  output.  Press  the 

space  bar  to  resume  output. 

j  enter  |  Performs  a  carriage  return  or  executes  the 

current  command  line. 
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Sample  Session 


Although  BASIC09  has  several  functions  or  modes,  they  all  work 
together  to  make  programming  as  simple  as  possible.  The  easiest 
way  to  learn  how  BASIC09  and  its  functions  operate  is  to  write 
and  run  a  program.  This  chapter  provides  sample  statements 
and  instructions  to  help  you  learn  how  to  use  BASIC09. 

To  create  and  execute  a  program: 

1.  Load  BASIC09  and  enter  the  edit  mode, 

2.  Type  the  BASIC  program. 

3.  Enter  the  system  mode  and  test  the  program's  execution. 

4.  Debug  the  program,  (Correct  any  programming  errors.) 

5.  Save  the  completed  program  on  disk. 

6.  Load  the  program  into  memory  and  use  it. 

To  begin  the  program,  execute  BASIC09.  To  be  sure  you  have 
enough  room  in  which  to  work,  reserve  a  workspace  of  10,000 
bytes  by  typing: 


baaic09    #1  0K  [ENTER 


The  BASIC09  system  mode  prompt,  B:,  appears  after  the  copy- 
right message.  In  the  system  mode,  you  can  do  such  things  as 
save  and  load  procedures,  change  workspace  size,  and  rename 
and  delete  procedures. 

Creating  a  Procedure 

To  write  procedures,  you  must  be  in  the  edit  mode.  "You  get  there 
by  typing: 


ENTER 


This  causes  the  screen  prompt  to  change  to  E : ,  and  the  screen 
displays: 

PROCEDURE  Program 

Because  you  didn't  give  a  program  name  when  you  entered  =, 
BASIC09  selects  the  name  Program  for  you.  Now,  you  must 
write  the  code  to  make  Program  do  something. 


2-1 


BASIC09  Reference 


Commands  and  Program  Lines 

There  are  two  responses  you  can  give  at  the  edit  mode  prompt. 
You  can  type  an  edit  command,  or  you  can  type  a  program  line. 
If  you  type  a  program  line,  you  must  type  a  space  as  the  first 
character  in  the  line.  If  you  type  an  edit  command,  do  not  pre- 
cede it  with  a  space.  To  make  listings  easier  to  read,  this  man- 
ual uses  the  symbol  D  to  indicate  spaces  before  every  line.  It  also 
uses  the  D  symbol  in  some  procedure  lines  to  indicate  the  correct 
number  of  spaces  needed.  Whenever  you  see  either  a  space  or  a  C 
symbol  in  a  procedure  you  are  typing,  press  the  space  bar. 

To  type  the  procedure  in  this  chapter,  begin  each  line  at  the  E : 
prompt.  After  typing  a  line,  check  it  for  mistakes.  If  you  make  a 
mistake,  use  (*3  to  move  the  cursor  back.  Correct  the  mistake. 
Then,  type  the  remaining  portion  of  the  line.  If  there  are  no  mis- 
takes, press  [  ENTER  |. 

BASIC09  checks  each  line  when  you  press  |  enter  |.  If  you  make  a 
mistake  in  syntax  or  form,  BASIC09  displays  an  error  message. 
An  arrow  points  to  the  place  in  the  program  line  where  the  error 
occurred,  and  a  message  number  indicates  the  type  of  error. 
Refer  to  Appendix  A  for  an  explanation  of  the  error  codes. 

If,  after  you  enter  a  line,  you  find  that  you  made  a  mistake,  type 
d  |  enter  |  to  delete  the  line.  Then,  retype  the  line.  Later,  the  man- 
ual tells  you  how  to  change  text  in  existing  lines. 

The  following  program  helps  you  do  a  bit  of  arithmetic.  To  get  a 
feel  for  BASIC09,  type  and  execute  the  program  as  directed. 
Remember,  when  you  see  either  a  space  or  D,  press  the  space  bar, 

CDIM   NUMBER1 ,NUMBER2: INTEGER 
ZINPUT   Type    "Number  ..." ;NUMBER1 

GINPUT   "Type   another " ;NUMBER2 

DPRINT   "The    sum   of    the    numbers    is...    " ; 

DPR  I  NT   NUMBER1     ♦    NUMBER2 

DEND 
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Executing  a  Procedure 

To  execute  the  procedure,  quit  the  edit  mode  by  typing  q  [  enter  1 
The  compiler  further  processes  your  procedure,  and  the  B: 
prompt  reappears.  To  execute  the  program,  type; 


run    ENTER 


Type  in  numbers  when  asked,  and  the  procedure  produces  their 
sum.  If  you  want  to  save  the  program  on  disk,  the  next  chapter 
tells  you  how.  Chapter  4  introduces  several  other  edit  mode  com- 
mands to  search,  display,  insert,  and  change  programs  lines  and 
text. 
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The  System  Mode 


The  BASIC09  command  interpreter  processes  system  commands. 
At  the  B:  prompt,  you  can  enter  system  commands  in  either 
upper-  or  lowercase  letters.  Some  commands  operate  on  the  pro- 
cedures in  the  workspace.  Others  provide  functions  independent 
of  any  procedures.  Following  is  a  list  of  all  system  commands 
and  their  purposes. 


Command 


Function 


$ 


BYE  or 


CTRL      BREAK 


CHD 
CHX 

fENTERl  or  DIR 

EDIT  or  E 
KILL 

LIST 

LOAD 

MEM 

PACK 

RENAME 

RUN 

SAVE 


Calls  the  shell  command  interpreter  to  execute 
an  OS-9  command. 

Returns  you  to  the  OS-9  system  or  to  the  pro- 
gram that  called  BASIC09. 

Changes  the  current  OS-9  data  directory. 

Changes  the  current  OS-9  execution  directory. 

Displays  the  name,  size,  and  variable  storage 
requirement  of  each  procedure  in  the 
workspace. 

Enters  the  procedure  editor-compiler  mode. 

Erases  one  or  more  procedures  from  the  work- 
space. 

Displays  a  formatted  listing  of  one  or  more 
procedures. 

Loads  all  procedures  from  a  disk  file  into  the 
workspace. 

Displays  in  bytes  the  current  workspace  size, 
or  reserves  a  specified  amount  of  memory  for 
the  workspace. 

Condenses  (compiles)  one  or  more  procedures. 

Changes  a  procedure's  name. 

Causes  a  procedure  in  the  workspace  to 
execute. 

Writes  one  or  more  procedures  to  disk. 
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Renaming  Procedures 

BASIC09's  RENAME  function  is  important  for  two  reasons: 
First,  it  lets  you  load  into  the  workspace  procedures  that  have 
the  same  name.  After  you  rename  the  workspace  procedure  you 
can  load  the  second  file.  Second,  if  you  let  BASIC09  use  the 
default  procedure  name,  "Program,"  you  can  rename  the  proce- 
dure before  saving  it  to  disk.  By  doing  this,  you  avoid  writing 
over— and  destroying — an  existing  procedure  file. 

To  change  the  name  of  the  procedure  you  created  in  the  previous 
chapter  from  Program  to  Add,  type: 


rename   program    add  |  ENTER  | 

Listing  Procedure  Names 

You  can  use  the  DIR  command  to  see  if  RENAME  worked  prop- 
erly. DIR  displays  the  names  and  sizes  of  all  procedures  in  mem- 
ory. Because  programmers  use  this  command  frequently,  the 
system  recognizes  a  shorthand  call.  Instead  of  typing  d  i  r  |  enter  |, 
you  only  need  to  press  |  ewer  |.  This  displays  a  table  of  the  proce- 
dures in  the  following  format: 


Home 

P 

roc-Si  ze 

Data-Size 

•  add 

182 

32 

addl 

217 

42 

add2 

218 

42 

2198    fi 

•ee 

Proc-Size  refers  to  the  number  of  memory  bytes  required  for  the 
procedure.  Data-Size  refers  to  the  number  of  memory  bytes 
required  for  the  procedure's  variables  and  data  structures.  The 
asterisk  indicates  the  current  procedure.  System  commands  act 
on  the  current  procedure  unless  you  indicate  otherwise. 

The  last  line  of  the  DIR  display  tells  you  how  many  free  bytes  of 
memory  remain  in  the  BASIC09  workspace. 

Listing  Procedures 

You  can  use  the  LIST  command  to  view  procedure  lines.  To  dis- 
play the  current  procedure,  type: 


list  I  ENTER  I 
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For  example,  this  is  the  listing  of  a  procedure  named  Alpha.bak: 

PROCEDURE    Alpha_bak 
0000  DIM   A:STRING 


0007 

DIM  T: INTEGER 

000E 

000F 

PRINT  "Here  Is  the  alphabet 

backwards : " 

0032 

PRINT 

0034 

FOR  T=90  TO  65  STEP  -1 

004A 

PRINT  CHR$CT); 

0051 

PRINT  "  "j 

0057 

NEXT  T 

0062 

PRINT 

0064 

PRINT 

0066  END 

When  you  list  a  BASIC09  procedure,  the  system  precedes  each 
line  with  a  relative  storage  address.  The  relative  address  of  the 
first  procedure  line  is  always  0.  In  the  previous  example,  the 
beginning  address  of  the  second  procedure  line  in  the  workspace 
is  07  units  from  the  beginning.  The  beginning  address  of  the 
third  line  is  0E  hexadecimal  (14  decimal)  storage  units  from  the 
procedure  beginning. 

These  I-Code  addresses  provide  a  way  for  the  compiler  to  let  you 
know  where  it  finds  an  error  when  one  occurs. 

Because  BASIC09  compiles  programs  into  I-Code,  it  must  disas- 
semble them  before  it  can  display  them  on  the  screen.  This 
means  that  the  lines  might  not  look  exactly  as  typed.  For 
instance,  BASIC09  converts  lowercase  keywords  (command 
names)  to  uppercase.  BASIC09  also  eliminates  some  spaces.  If 
your  program  uses  control  statements  such  as  IF/THEN,  FOR/ 
NEXT,  and  LOOP/ENDLOOP,  the  lines  in  these  decision  mak- 
ing or  looping  structures  are  indented  as  shown  in  the 
Alpha.bak  example.  Regardless  of  the  appearance  of  your  listed 
procedures,  they  execute  correctly  if  you  type  their  commands 
correctly. 
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Listing  Procedures  to  a  File 

There  might  be  times  when  you  want  to  send  a  formatted  proce- 
dure listing,  including  I-Code  addresses,  directly  to  a  file.  You 
can  do  this  using  OS-9's  redirection  symbol,  >.  To  save  the 
Alpha.bak  procedure  on  a  file  named  Alpha.list  in  the  current 
data  directory,  type: 

list    alpha. bale    >alpha.  list  |  ENTER] 

If  you  have  several  procedures  in  the  workspace  and  want  to  list 
more  than  one  to  a  disk  file,  separate  the  procedure  names  with 
commas,  like  this: 

list    alpha .one ,olpha. two, alp ha. three    >alpha.all 
[TnTER] 

In  both  of  the  preceding  cases,  the  system  creates  the  Alpha.list 
file  and  stores  the  specified  listings  in  it.  If  you  use  a  file  name 
that  already  exists,  BASIC09  displays  the  prompt: 

Rewrite?: 

If  you  press  (T),  the  system  destroys  the  original  file  and  over- 
writes it  with  the  new  listing.  If  you  press  QQ,  the  LIST  process 
terminates. 

If  you  wish  to  list  a  procedure,  or  group  of  procedures,  to  a  file 
that  is  not  in  the  current  data  directory,  be  sure  to  specify  the 
complete  pathlist,  such  as: 

list    alpha.bak    >    /d1 /programs /alpha,  rev  j ENTER  | 

Listing  Procedures  to  a  Printer 

In  the  same  manner  as  you  list  procedures  to  a  disk  file,  you  can 
list  one  or  more  procedures  to  your  printer.  Make  certain  your 
printer  is  connected  and  turned  on,  then  again  use  the  redirec- 
tion symbol,  but  this  time  specify  the  printer  device,  like  this: 


Or: 


list    alpha.bak    >  /  p  |  ENTER  I 

list    alpha. one, alpha,  two,  alpha,  three    >  /  p  [  EMTERl 
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Using  a  Wildcard 

Using  the  OS-9  wildcard,  *,  you  can  list  all  procedures  in  the 
workspace.  For  instance,  if  the  procedures  Alpha.one,  Alpha.two, 
and  Alpha.three  exist,  list  them  to  the  screen  by  typing: 


list*  I  ENTER  I 


Send  the  list  to  a  file  by  typing: 


list*    alpha. all  |  ENTER  1 

Or  send  the  list  to  your  printer  by  typing: 

list*    /p 

Note:  When  you  use  the  wildcard,  the  name  of  the  file  or 
device  to  receive  the  listing  immediately  follows  the  LIST* 
command.  Do  not  use  the  redirection  symbol. 

Saving  Procedures 

You  can  save  one  or  more  procedures  to  disk  using  the  SAVE 
command.  Unlike  LIST,  SAVE  does  not  include  relative 
addresses.  However,  the  syntaxes  for  the  SAVE  and  LIST  com- 
mands are  identical.  To  save  the  procedure  Alpha.bak  to  the  cur- 
rent data  directory,  type: 

save    alpha.bak    alpha.bak  [ENTER] 

If  Alpha.bak  is  the  current  procedure,  you  can  save  it  in  a  file 
named  Alpha.bak  by  typing  aave  |  enter  [. 

To  save  all  of  the  procedures  in  the  workspace  to  a  file  named 
All.programs  in  the  current  data  directory,  type: 


save*    ftll  .programs  |ENT£R] 

As  with  LIST,  to  save  one  or  more  procedures  in  a  file  that  is 
not  in  the  current  data  directory,  make  sure  you  specify  a  com- 
plete pathlist. 

To  save  all  the  files  in  the  workspace  to  a  disk  file  with  the 
same  name  as  the  current  procedure,  type  save*  |  enter  |. 

If  the  disk  file  you  specify  does  not  exist,  BASIC09  creates  it.  If 
it  does  exist,  the  system  displays  the  prompt: 

Rewrite?: 
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Press  (Y)  to  write  over  the  old  file  with  the  specified  file.  The  old 
file  is  destroyed. 

Press  (TJ  to  terminate  the  SAVE  operation. 

Loading  Procedures 

To  bad  a  saved  procedure  back  into  BASIC09's  workspace,  use 
the  LOAD  command  and  specify  the  appropriate  pathlist.  For 
instance,  if  your  current  directory  is  still  the  directory  contain- 
ing Alpha.bak,  load  the  procedure  by  typing: 


load   alpha.bak  [ENTER! 

To  load  Alpha.bak  from  the  PROGRAMS  directory  on  Drive  /Dl, 
type: 

load    /d1  /programs /alpha,  rev  [ENTER] 

%u  can  run  and  edit  a  loaded  procedure  in  exactly  the  same 
manner  as  you  would  a  procedure  you  created. 

You  can  load  any  number  of  procedures  into  the  workspace  as 
long  as  your  computer  has  sufficient  memory.  However,  be  care- 
ful that  you  do  not  load  a  procedure  with  the  same  name  as  a 
procedure  already  existing  in  the  workspace.  If  you  do,  the  new 
procedure  overwrites  (destroys)  the  original  procedure.  You  can 
rename  workspace  procedures  to  avoid  this  problem. 

Deleting  Procedures  from  the  Workspace 

You  can  clear  the  workspace  of  one  or  more  procedures  using  the 
KILL  command.  For  instance,  to  remove  Alpha.bak  from  the 
workspace,  type: 


kill    alpho.bak  [  ENTER  | 

To  remove  more  than  one  procedure  from  the  workspace,  sepa- 
rate the  procedure  names  with  commas.  To  delete  Alpha,  one  and 
Alpha.two,  type: 


kill    alpha  .one, alp  ha.  two  j  ENTER  | 

To  clear  the  entire  workspace,  regardless  of  the  number  of  proce- 
dures it  contains,  use  the  BASIC09  wildcard,  *.  Type: 


kill*  I  ENTER  I 
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Changing  Directories 

You  change  working  directories  in  BASIC09  and  OS-9  in  the 
same  manner,  by  using  the  CHD  and  CHX  commands,  CHD 
changes  the  data  directory,  and  CHX  changes  the  execution 
directory. 

BASIC09  saves  files  in,  or  loads  files  from,  the  data  directory, 
unless  you  specify  differently  in  the  command  pathlist.  It  stores 
packed  procedures  in,  or  loads  PACKed  procedures  from,  the  exe- 
cution directory,  unless  you  specify  differently  in  the  command's 
pathlist. 

Also,  if  you  want  to  access  OS-9  commands  from  BASIC09,  the 
system  first  looks  for  the  commands  in  memory.  If  they  are  not 
there,  it  looks  for  them  in  the  execution  directory,  unless  you 
specify  differently. 

If  your  data  directory  is  the  ROOT  directory,  and  you  wish  to 
change  to  a  directory  named  PROGRAMS  that  is  a  subdirectory 
of  the  ROOT  directory,  type  the  following  command  from  the 
command  mode  B:  prompt 


chd    progroma  |  ENTER  | 

If  your  current  execution  directory  is  the  system's  CMDS  direc- 
tory, and  you  want  to  change  to  a  CMDS  directory  in  the  sub- 
directory BASIC,  type: 


chx    basic/cmds  I  ENTER  ] 


Whenever  you  change  to  a  directory  other  than  an  immediate 
subdirectory,  specify  a  complete  pathlist. 

Executing  OS-9  Commands 

BASIC09  lets  you  use  OS-9  commands  at  any  time  from  the  sys- 
tem mode.  To  do  so,  precede  the  command  with  a  dollar  sign  ($). 
For  instance,  to  took  at  the  current  data  directory,  type: 


$dir  I  ENTER  1 


To  view  the  current  execution  directory,  type: 


Jdir     x   I  ENTER  I 
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All  OS-9  commands  are  available,  and  you  can  copy  files,  format 
diskettes,  list  files,  or  use  any  other  functions  from  the  system 
mode.  The  only  restriction  is  that  your  computer  must  have 
enough  free  memory  to  handle  the  command  you  call.  If  you  find 
that  there  is  not  enough  memory,  try  using  the  MEM  command 
to  reduce  reserved  memory.  Then,  try  the  command  again. 

Auto-Execute  Procedures 

The  BASIC09  compiler  makes  two  passes  through  the  procedures 
you  write.  When  you  enter  the  command,  the  compiler  performs 
an  initial  compilation,  checking  for  any  syntax  errors.  When  you 
leave  the  edit  mode,  the  system  compiles  the  procedure  a  second 
time  and  checks  for  any  programming  errors.  With  the  PACK 
command,  you  can  further  compile  your  procedures  so  that  they 
are  smaller  and  execute  even  faster. 

PACK  causes  an  extra  compiler  pass  that  removes  names,  line 
numbers,  and  non-executable  statements.  Before  packing  a 
procedure,  be  sure  you  save  it.  Unless  you  do  so,  you  can- 
not make  further  changes  to  the  procedure. 

Once  you  pack  a  file,  you  cannot  list  or  edit  the  packed  version. 
However,  if  you  save  the  procedure  to  disk  before  packing,  you 
can  still  list  and  edit  the  original  file,  then  pack  it  again. 

When  you  save  a  packed  procedure  on  disk,  BASIC09  does  not 
normally  store  it  in  the  data  directory.  Because  the  procedure  is 
now  executable,  the  system  stores  it  in  the  current  execution 
directory. 

For  instance,  to  convert  Alpha.bak  to  a  packed  procedure  in  the 
execution  directory,  type: 


pack    alpha.bak  |  ENTER  | 

If  you  want  to  save  a  packed  procedure  under  a  different  file- 
name, use  the  OS-9  redirection  symbol: 

pack    alpha.bak    >    backwards  | ENTER] 

After  packing  a  procedure,  you  can  delete  it  from  the  workspace. 
If  you  then  run  it,  BASIC09  automatically  loads  the  file  from 
disk  and  executes  it. 

The  following  is  a  sequence  of  commands  that  demonstrate  pack- 
ing and  executing  a  procedure  named  Alpha.bak: 
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pack    alpha,  bak   |  ENTER  1 


kill    alpha. bak   |  ENTER  | 


run    alpha. bnk    [  ENTER  | 


packs  the  procedure  and  stores 
it  in  the  execution  directory. 

deletes  the  p-ocedure  from  the 
workspace, 

loads  the  file  into  memory 
outside  the  workspace  and 
executes  it. 

kill  a  1  pha .  ba  k  [  enter  I       deletes  the  module  from 

memory 

"You  do  not  need  to  kill  the  file  immediately  after  execution,  but 
until  you  do,  the  file  reduces  available  memory. 
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You  briefly  used  the  BASIC09  built-in  editor  to  create  the  Add 
procedure  in  Chapter  2.  In  addition  to  the  features  you  learned 

there,  the  editor  has  other  important  functions. 

Although  you  can  use  any  text  editor  or  word  processor  to  write 
BASIC09  procedures,  the  BASIC09  editor  offers  two  handy 

features: 

•  It  is  both  string  and  line  number  oriented.  You  can 
search  for  strings  of  characters,  and  replace  them,  and 
you  can  reference  text  with  optional  line  numbers. 

•  It  interfaces  with  the  compiler  and  decompiler.  This  fea- 
ture lets  BASIC09  check  continuously  for  syntax  errors 
and  enables  you  to  use  procedures  that  conserve  memory. 

Edit  Commands 

The  following  is  a  summary  of  the  edit  commands: 
Command  Function 


| ENTER  | 

+  number 
+  * 
-number 

.* 

text 

ntext 

n 

c/strl/str2/ 


Moves  the  edit  pointer  to  the  next  line.  Causes 
a  command  to  execute. 

Moves  the  edit  pointer  ahead  number  lines. 

Moves  the  edit  pointer  to  the  last  line. 

Moves  the  edit  pointer  back  number  lines. 

Moves  the  edit  pointer  to  the  first  line. 

Inserts  an  unnumbered  text  line  before  the 
current  line. 

Inserts  the  line  numbered  n  in  its  correct 
numeric  position. 

Moves  the  edit  pointer  to  the  line  numbered  n. 

Changes  the  next  occurrence  of  strl  to  str2. 
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Command 


Function 


c*lstrl/str2/  Changes  all  occurrences  of  strl  to  str2. 

d  Deletes  the  current  line. 

d*  Deletes  all  the  lines  in  the  procedure. 

1  Lists  the  current  procedure  line. 

1*  Lists  all  the  procedure  lines. 

q  Terminates  the  edit  session. 

r  Renumbers  lines  beginning  at  the  current  line 

in  increments  of  10. 

r*  Renumbers  all  lines  in  increments  of  10. 

r  n  Renumbers  lines  beginning  at  Line  n  in 

increments  of  10. 

r  nl  n2  Renumbers  lines  beginning  at  Line  nl  in 

increments  of  n2. 

s  /string/  Searches  for  the  first  occurrence  of  string. 

8*  /string/  Searches  for  all  occurrences  of  string. 


Using  the  Editor 

The  easiest  way  to  understand  the  edit  commands  is  to  use 
them.  The  following  sections  show  you  the  functions  of  BASIC09 
edit  mode. 

The  manual  uses  line  numbers  in  the  following  procedure  to 
acquaint  you  with  all  the  functions  of  the  editor.  Remember, 
however,  line  numbers  are  not  required  with  BASIC09.  Proce- 
dures and  programs  without  line  numbers  are  shorter,  faster, 
and  easier  to  read. 

First,  you  need  a  procedure  with  which  to  work.  Position  your- 
self in  the  system  mode.  Then,  type  this  line: 


e    prose  |  ENTER  | 
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Now,  type  the  following.  (Remember,  the  small  rectangle  repre- 
sents a  space.) 

1100    DIM   PHRASES<30>:STRING 

1120    FDR    T-1    TO    30 

3130    READ    PHRASESU) 

J140    NEXT   T 

HI  60    PRINT 

G170    FIRST-RND<10> 

0180    SEC0ND-RNDC9J+11 

Q190   THIRD-RND(9>+21 

D200    PRINT   PHRASES(FIRST); 

D210    PRINT    PHRASES(SECDND); 

Q220    PRINT   PHRASES(THIRD); 

Q24  0    PRINT 

3300  DATA  "LoveD" ,"An  orangeQ" , 

"Human it yD" ,"A  kissC" 

1310  DATA  "A  dark  c  loud'H" ,  "A  goose  featherC", 

"A  PopsicleD" 

1320  DATA  "Home  cook i ng~" , "Cold  pizzaD", 

"Rock  n'  RollD" 

1330  DATA  "is  charming  1 i keD" , "makes  me  dream  of!" 

1340  DATA  "is  as  sticky  asU'V'can  ooze 

like!" ."smells  likeD" 

I3B0  DATA  "can  be  as  tough  to  forget  asC","can 

hurt  like!" 

1360  DATA  "can  be  as  cynical  asC", "makes  a  mockery 

ofl" 

1370  DATA  "drives  me  as  crazy  asl" 

1380  DATA  "a  sticky  1 ol 1 ipop . " ,"a  web  of 

intrigue." 

1390  DATA  "castor  oil.", "a  chocolate  bath.", "a 

broken  toe." 

1400  DATA  "honey  and  th ings . " , "per sonal 

defeat. ","o  wet  diaper." 

1410  DATA  "strange  happenings .", "a  pennyiess 

purse." 

When  you  finish  typing  the  procedure,  type  q  |  enter  I  to  return  to 
the  system  mode.  Now  you  can  test  the  program  by  typing 
either: 


run  |  ENTER  | 
or 


run    prose  |  ENTER  | 
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After  trying  the  procedure,  return  to  the  edit  mode  by  typing  e 

I  ENTER  1. 

After  displaying  the  procedure's  name,  the  editor  displays  Line 
100  preceded  by  an  asterisk.  The  asterisk  lets  you  know  which 
line  is  the  current  line  (or  the  line  at  which  the  edit  pointer  is 
located). 


Searching  Through  a  Procedure 

"You  can  examine  a  procedure  in  three  ways: 

•  Press  |  eptter  I  to  display  the  procedure  one  line  at  a  time. 

•  Skip  through  the  procedure  to  a  particular  line. 

•  List  part  or  all  of  the  procedure  to  the  screen. 

When  you  use  either  of  the  first  two  methods,  the  line  you  select 
to  display  becomes  your  current  line.  When  you  use  the  third 
method,  the  current  line  does  not  change. 


Using  |  ENTER  1 

If  you  are  still  positioned  at  Line  100,  but  want  to  examine  the 
first  line  of  data,  Line  300,  press  I  enter  I  12  times  to  move  down. 


Using  the  Plus  Sign  to  Move  Forward 

Another  method  of  moving  to  a  specific  line  is  to  type  a  plus 
sign  followed  by  the  number  of  lines  you  need  to  advance  to  get 
there.  Positioned  at  Line  100,  you  can  type: 


+  12  I  ENTER  I 


Whether  you  press  [  enter  I  or  use  the  plus  sign,  the  last  line  dis- 
played is  now  your  current  line. 
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Accessing  a  Line  Using  the  Line  Number 

The  third  way  to  move  to  a  particular  line  is  to  type  the  line 
number,  followed  by  |  enter  |.  For  instance,  to  jump  back  to  Line 
100,  type: 


1  00  I  ENTER  I 


The  editor  displays  Line  100  and  makes  it  your  current  line. 


Using  the  Minus  Sign  to  Move  Backward 

In  the  same  manner  that  you  move  forward  in  the  procedure 
using  the  plus  sign,  you  can  move  backward  using  the  minus 
sign,  or  hyphen. 

Type  30  0  [  enter  |  to  return  to  Line  300.  To  display  Line  240  and 

make  it  your  current  line,  type: 


-     ENTER 


To  display  Line  190  and  make  it  your  current  line,  type: 


-4  |  ENTER  | 


The  Global  Symbol 

The  BASIC09  editor  also  makes  use  of  the  asterisk  as  a  global 
symbol.  For  instance,  following  a  command  with  an  asterisk 
causes  that  command  to  affect  the  entire  procedure. 

This  feature  lets  you  move  quickly  to  the  beginning  and  end  of 
the  procedure.  To  return  to  Line  100,  the  first  line,  type: 


-  *     ENTER 


To  move  to  the  end  of  the  procedure,  past  all  the  numbered  lines, 
type: 


+  *     ENTER 
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Using  LIST 

The  LIST  command  lets  you  select  one  or  more  lines  for  display 
on  your  screen,  To  see  this,  make  the  first  line  your  current  line, 
then  type: 


1   I  ENTER  I 


To  list  one  or  more  lines,  type  the  LIST  command  followed  by  the 
number  of  lines  you  want  displayed.  For  instance,  typing  is 
I  enter  [  causes  the  current  line  and  four  others  to  appear  on  the 
screen,  as  shown  in  the  following  sequence  of  commands  and  the 
resulting  display: 

-«  | enter | 
15  I  ENTER  I 


PROCEDURE  Prose 

100  DIM  PHRASESO0):  STRING 

120  FOR  T>1  TO  30 
130READ  PHRASES<T) 
140  NEXT  T 
160  PRINT 

You  can  also  use  LIST  with  the  BASIC09  global  symbol,  *.  Typ- 
ing an  asterisk  after  the  LIST  command  produces  a  listing  of 
the  entire  procedure. 

Deleting  Lines 

Earlier,  the  manual  showed  that  you  can  delete  the  current  line 
by  typing  d  I  enter  |.  Because  this  is  such  a  simple  process,  be 
sure  you  don't  do  it  by  accident.  Removing  the  wrong  line,  or  too 
many  lines,  is  very  frustrating  in  a  complex  procedure. 

You  can  also  remove  a  group  of  lines  from  a  procedure  by  typing 
d,  followed  by  the  number  of  lines  you  want  to  delete.  This  com- 
mand deletes  the  current  line  and  specified  following  lines. 
Again,  be  careful. 

You  can  remove  all  of  the  lines  in  a  procedure  by  using  the 
global  symbol,  *.  Typing  d»  I  enter  |  erases  all  procedure  text. 
However,  the  procedure  name  still  resides  in  the  workspace.  To 
delete  an  entire  procedure,  including  the  name,  use  the  KILL 
command  from  the  system  mode. 
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If  you  decide  you  don't  like  the  nouns  used  in  the  DATA  lines  of 
the  Prose  procedure,  erase  all  of  the  DATA  lines  containing 
nouns  (Lines  300-320)  and  replace  them.  To  do  so,  make  Line 
300  your  current  line  by  typing: 


300  I  ENTER  I 


Then  type: 


d  I  ENTER  I 


Line  300  disappears  and  Line  310  takes  its  place  as  the  current 
line. 

An  alternate  method  of  deleting  the  DATA  lines  uses  only  one 
command.  To  delete  Lines  300  through  410,  follow  the  DELETE 
command  with  the  number  of  lines  you  want  to  remove — in  this 
case,  three: 


d3  I  ENTER  I 


Lines  300,  310,  and  320  disappear.  Line  330  becomes  the  cur- 
rent line.  Move  back  a  line  to  check  that  the  deletions  worked. 
The  line  numbers  now  skip  from  240  to  330. 

Now,  you  need  new  nouns  for  the  procedure.  Type  them  in  the 
same  style  as  the  old  lines,  such  as: 

D300    DATA    "A    Telephone!!,  "A    tickled", 

"A    girlU'V'A   boyD" 

H315   DATA   "Bad    luckD" ."MoneyQ" ,"A    bad    betl", 

"A    lumpy   bedG" 

1320    DATA    "A   deep    thoughtU'V'Sunl ightl" 

Save  a  copy  of  your  procedure  to  disk  by  exiting  the  editor  and 
using  the  SAVE  command.  Then  return  to  the  edit  mode  and  try 
the  global  delete  by  typing: 


d*  I enter  1 


Changing  Text 

Using  CHANGE  tells  the  editor  to  search  for  existing  text  and 
replace  it  with  new  text.  CHANGE,  like  DELETE,  can  easily 
cause  unwanted  results  if  you  are  not  careful. 
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The  CHANGE  command  requires  that  you  use  delimiters  to  sep- 
arate the  command  from  the  search  text,  and  to  separate  the 
search  text  from  the  new  text.  "Vlbu  can  select  any  of  the  following 
characters  for  a  delimiter,  as  long  as  it  does  not  appear  in  either 
the  search  text  or  the  new  text: 

!#%*&()■+  ={}[]"  "<>,.?/  \  | 

Do  not  use  the  global  symbol  (*)  for  search  and  replace  opera- 
tions. This  manual  uses  a  slash  (/)  as  the  CHANGE  delimiter. 

The  following  steps  outline  the  correct  use  of  CHANGE: 

1.  Position  the  editor  either  before  or  on  the  line  in  which 
you  want  to  make  a  change. 

2.  Type  c  (for  CHANGE).  Do  not  use  a  preceding  space. 

3.  Type  a  delimiter  character,  such  as  /. 

4.  Type  the  characters  to  be  changed,  following  them  with 
the  delimiter. 

5.  Type  the  new  text,  followed  by  the  delimiter. 

6.  Press  [ENTER]. 

Note:  It  is  a  good  idea  to  turn  on  OS-9's  upper-  and  lower- 
case function  before  attempting  change  or  search  opera- 
tions. If  you  do  not,  you  cannot  tell  whether  the  text  you 
want  to  find  is  upper-  or  lowercase,  or  some  combination  of 
the  two.  If  you  type  the  wrong  case,  the  change  or  search 
fails. 

In  case  you  didn't  notice  when  typing  the  procedure,  Line  410 
contains  an  incorrectly  spelled  word,  pennyless.  To  correct  this 
error,  type  the  following: 


c/pennyl ess /penni less /  |  ENTER  | 

Immediately,  the  editor  displays  Line  410,  with  pennyless 
changed  to  penniless. 

Suppose  you  decide  to  change  the  number  of  sentence  combina- 
tions available  in  Prose.  The  procedure  now  has  30  data  entries. 
If  you  add  five  subjects,  five  verb  phrases,  and  five  objects,  the 
procedure  also  needs  other  changes  (for  instance,  the  DIM  state- 
ment in  Line  100,  the  loop  size  in  Line  120,  and  the  RND  state- 
ments in  Lines  170  through  190). 
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A  quick  way  to  change  the  number  30  in  Lines  100  and  120  is 
to  use  CHANGE'S  global  function.  To  change  all  occurrences  of 
30  to  45,  position  the  editor  at  Line  100,  and  type: 


C*/30/4S/  I  enter  I 


Use  the  CHANGE  and  global  CHANGE  functions  to  adjust  the 
RND  statement  values  in  Lines  170,  180,  and  190. 

As  well  as  making  changes,  you  can  use  the  CHANGE  command 
to  quickly  delete  portions  of  text  within  a  line.  To  do  this,  type 
delimiters  without  new  text,  in  this  fashion: 


c/Dfeather//  |  ENTER  | 

This  command  changes  the  text  A  goose  feather  in  Line  210 
to  A   gooae. 


Searching  for  Text 

The  editor's  SEARCH  command,  S,  works  in  the  same  manner 
as  the  CHANGE  command.  However,  SEARCH  only  requires 
you  to  specify  a  block  of  text  to  find. 

With  SEARCH,  you  use  delimiters  to  enclose  the  text  to  find.  To 
test  the  function,  position  the  editor  at  the  beginning  of  text  by 
typing: 


-•  |  ENTER  | 

Now,  search  for  the  word  phrases,  by  typing: 


S/phrasea/  [  ENTER  | 

The  screen  displays: 

►0002    100   DIN   phrases(30):STRING 

To  find  all  occurrences  of  phrases  throughout  the  procedure,  use 
the  global  symbol.  Type: 


s*/phrasea/  |  ENTER  \ 
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Renumbering  Lines 

The  RENUMBER  command,  R,  reorders  all  numbered  lines  and 
all  references  to  numbered  lines.  "You  can  give  RENUMBER 
either  one  or  two  parameters.  The  first  is  the  beginning  line 
number.  The  second  is  the  increment  you  want.  The  default 
increment  is  10. 

Ear  instance,  the  Prose  procedure  line  numbers  skip  from  Line 
100  to  Line  120,  You  can  renumber  the  entire  procedure  by  mov- 
ing the  editor  to  Line  100,  and  then  typing: 


r     10  |  ENTER  I 


To  change  the  numbering  to  increments  of  5,  beginning  at  Line 
100,  type: 


r    100,5  |  ENTER  | 

You  can  also  change  line  numbering  in  portions  of  the  procedure. 
To  do  this  move  the  editor  to  the  line  where  you  want  the  new 
numbering  to  begin.  Then,  type  in  the  new  parameters.  To 
renumber  Line  100  as  Line  200  and  continue  with  increments  of 
10,  position  the  editor  at  Line  100.  Then,  type: 


r     200  ,1  0  I  ENTER  I 


If  you  are  not  positioned  at  the  first  line  of  a  procedure,  but  you 
wish  to  renumber  all  lines,  you  can  use  the  global  symbol  to  do 
the  job.  From  anywhere  in  the  procedure,  type: 


r*     100,10  I  ENTER  I 


This  renumbers  the  entire  procedure  in  increments  of  10. 

Adding  Lines 

There  are  two  ways  to  add  new  lines  to  a  procedure.  You  can: 

•  Position  the  editor  one  line  below  the  position  for  the  new 
line.  Then,  type  the  new  line  and  press  [  enter  |.  When 
inserting  lines  without  numbers,  be  sure  to  type  a  space 
as  the  first  character  of  the  line  to  tell  the  editor  that 
the  following  text  is  a  new  procedure  line. 

•  Type  a  new  line,  giving  it  a  line  number  that  falls 
between  two  existing  line  numbers. 


4-10 


The  Edit  Mode  1 4 


The  following  procedure  adds  more  choices  to  the  Prose  program. 
It  also  adds  a  feature  that  lets  you  press  |  enter  |  for  additional 
output,  rather  than  having  to  rerun  the  procedure.  Use  the 
information  presented  in  this  section  to  help  you  insert  the  new 
lines  into  your  program.  Because  you  must  change  some  lines, 
as  well  as  add  lines,  the  following  listing  includes  the  entire 
procedure. 

Referring  to  the  original  Prose  listing,  the  lines  to  change  are: 
100,  120,  170,  180,  and  190. 

The  lines  to  add  are:  110,  150,  230,  250,  260,  270,  305,  325, 
372,  374,  376,  420,  430. 

PROCEDURE  proae2 

100  DIM  PHRASES(4S):STRINO 

110  DIM  RESP0NSE:STRING 

120  FOR  T*1  TO  45 

130  READ  PHRASESCt) 

140  NEXT  T 

150  REPEAT 

160  PRINT 

170    FIRST-RNDOS) 

190    5EC0ND-RND(14>+16 

190    TH!RD"RNDC14>+31 

200  PRINT  PHRASESCFIRST); 

210  PRINT  PHRASESCSECOND); 

220  PRINT  PHRASESCTHIRD); 

230  PRINT 

240  PRINT 

250  PRINT  "aCIIiriCnriPreas  ENTER  for  another 

witticism. . ." 

260    INPUT   "ZnmXQUOr    press    the   SPACEBAR   and   press 

ENTER    to   end. . .".RESPONSE 

270  UNTIL  RESPONSES"' 

300  DATA  "Lovej'V'An  orongeC" ,"Humanl tyD" , 

"A  kiasL" 

305   DATA    "A   computerD" , "A    boolcD'V'MiseryD" 

310    DATA    "A   dark    cloudD'V'A    goose    featherD", 

"A    PopsicleU" 

320  DATA  "Home  cookingD" ,"Cold  pizzaD", 

"Rock  n'  RoIIl" 

325  DATA  "Snow  in  JuneD'V'A  glass  houseD" 

330  DATA  "is  charming  1 i keO" , "makes  me  dream  ofZ" 
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340  DATA  "is  as  sticky  oaD","can  ooze  likeD", 

"smells  likeC" 

350  DATA  "can  be  as  tough  to  forget  asD", 

"can  hurt  likeD" 

3G0  DATA  "can  be  as  cynical  asD", 

"makes  a  mockery  ofD" 

370  DATA  "drives  me  as  crazy  asD" 

372  DATA  "can  bother  me  1 i keD" , "bloc  kens  my  hopes 

like™ 

374  DATA  "can  tickle  me  likeD", "can  be  aa  funny 

asD" 

376  DATA  "has  the  effect  ofD" 

380  DATA  "a  sticky  lol lypop . " , "a  web  of 

lntr  igue . " 

398  DATA  "castor  oil.", "a  chocolate  bath.", "a 

broken  toe." 

400  DATA  "honey  and  things .", "persona  1 

defeat. ","a  wet  diaper." 

410  DATA  "strange  happenings ." ,"a  penniless 

purse . " 

420  DATA  "a  slimy  snake.", "a  bad  habit." 

430  DATA  "a  bad  memory  chip.", "a  good  fight.", "a 

silly   friend." 

The  Next  Step 

Even  the  best  programmers  make  mistakes — a  lot  of  them. 
BASIC09  provides  a  way  to  catch  programming  mistakes  quickly 
and  correct  them.  The  next  chapter  tells  you  about  BASIC09's 
powerful  debugging  functions. 
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The  Debug  Mode 


The  term  debug  refers  to  the  process  of  finding  programming 
errors  and  correcting  them.  BASIC09's  debugging  features 
include  symbolic  debugging  capabilities  that  let  you  examine 
variable  values  and  test  and  manipulate  procedures. 

With  Debug,  you  can: 

•  Examine  and  change  variables. 

•  Trace  procedure  execution.  Debug  lets  you  execute  proce- 
dures and  watch  them  run  in  slow  motion. 

•  Pause  procedure  execution. 

•  Resume  procedure  execution. 

•  Set  procedure  breakpoints  that  automatically  switch  to 
the  debug  mode. 

•  Select  the  use  of  degrees  or  radians  for  trigonometric 
functions. 

•  Perform  calculations. 

•  Call  OS-9  system  commands. 

Entering  the  Debug  Mode 

'You  enter  Debug: 

•  Automatically,  whenever  an  error  occurs  during  the  exe- 
cution of  a  procedure  (unless  you  have  included  an  ON 
ERROR  GOTO  statement  to  handle  the  error). 

•  Automatically,  when  a  procedure  executes  a  PAUSE 
statement. 

•  When  you  press  |  ctrl  ll"c]  during  the  execution  of  a 
procedure. 

You  can  tell  when  BASIC09  enters  the  Debug  mode  by  the 
appearance  of  the  D :  prompt.  When  you  see  D ; ,  followed  by  the 
cursor,  Debug  is  waiting  for  your  command. 

The  following  is  a  reference  of  all  the  Debug  commands  and  what 
they  accomplish: 
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Command 


Function 


BREAK 


CONT 
DEG/RAD 


Calls  OS-9's  command  shell  interpreter  to  run 
a  program  or  an  OS-9  command.  From  the 
Debug  prompt,  type  $,  followed  by  the  name  of 
the  program  or  command  you  want  to  execute. 


ENTER 


Example:  $  1  i  a  t    procedure one 

Sets  a  breakpoint  immediately  before  the  spec- 
ified procedure.  Use  this  command  to  re-enter 
Debug  when  one  procedure  calls  another. 

If  you  have  three  procedures  that  call  each 
other— Procl,  Proc2,  and  Proc3 — and  Proc3 
does  not  seem  to  pass  the  correct  values  to 
Proc2  when  it  returns,  set  a  breakpoint  at 
Proc2.  This  causes  BASIC09  to  enter  Debug 
before  re-entering  Proc2.  Yon  can  then  check 
your  variable  values. 

%u  can  use  one  breakpoint  for  each  active  pro- 
cedure. Debug  removes  breakpoints  immedi- 
ately after  encountering  them. 

A  procedure  must  run  before  you  can  set  a 
breakpoint  in  it.  Use  BREAK  to  stop  execution 
when  a  called  procedure  returns  to  a  proce- 
dure previously  executed. 

Example:  BREAK   proc2  |  enter  I 

Causes  procedure  execution  to  continue. 


Example:  cont  [  enter  I 


Selects  either  degrees  or  radians  as  the  unit  of 
measurement  for  trigonometric  functions.  DEG 
and  RAD  affect  only  the  current  procedure. 


Examples:  deg  [  enter  | 

rad  I  ENTER  I 
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DIR 


Q 


LET 


LIST 


PRINT 


STATE 


Displays  the  name,  size,  and  variable  storage 
requirements  of  each  procedure  in  the  work- 
space. The  current  working  procedure  has  an 
asterisk  before  its  name.  All  packed  proce- 
dures have  a  dash  before  their  names.  DIR 
also  shows  the  available  memory  in  the 
workspace. 

If  you  provide  a  pathlist,  DIR  sends  its  data  to 
the  specified  file. 

Example:  dir  [enter) 


dir    procedures  I  ENTER  I 

Terminates  execution  of  the  procedure,  closes 
any  open  paths,  and  exits  to  the  System  mode. 

Example:  q  |  enter  1 

Assigns  a  new  value  to  a  variable.  "You  must 
specify  variable  names  that  are  already  ini- 
tialized by  your  program.  In  the  Debug  mode, 
you  cannot  use  LET  to  copy  one  array  to 
another  array  as  you  can  in  BASIC 
procedures. 


Example:  let 

let 


a    :=    0 
fruit     : 


ENTER 


"oranges"  |  ENTER  | 


Displays  a  source  listing  of  the  suspended  pro- 
cedure. The  display  is  formatted  and  includes 
I-code  addresses.  An  asterisk  appears  to  the 
left  of  the  last  executed  statement. 

Example:  list  |  enter  | 

Displays  the  values  of  variables  used  in  the 
suspended  procedure.  You  cannot  introduce 
new  variable  names  in  the  Debug  mode,  and 
you  cannot  display  array  structures. 


Example:  print    fruit  |Tnter~1 


Lists  the  nestirtg  order  of  active  procedures. 
STATE  displays  the  highest-level  procedure  at 
the  bottom  of  the  calling  list.  The  lowest-level 
procedure  is  the  suspended  procedure. 


Example:  state  |  enter  | 
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STEP 


TRON/TROFF 


Causes  execution  of  the  suspended  procedure 
in  specified  increments.  For  example,  typing 
STEP  5  |  enter  )  executes  the  equivalent  of  the 
next  five  statements.  If  you  enter  STEP  with- 
out an  increment  value,  the  step  rate  is  1. 

Using  STEP  with  the  trace  function  lets  you 
observe  the  source  lines  as  they  execute. 

Because  compiled  I-code  contains  actual  state- 
ment memory  addresses,  the  top  or  bottom 
statements  of  loop  structures  execute  only 
once.  For  example,  in  FOR/NEXT  loops,  FOR 
executes  once,  and  the  statement  following 
FOR  appears  to  be  the  top  of  the  loop. 

Turns  on  or  turns  off  the  trace  function.  Trace 
on  (TRON)  causes  the  system  to  reconstruct 
the  compiled  code  of  each  statement  line  into 
source  code.  Debug  displays  the  source  code 
before  the  statement  is  executed.  If  the  state- 
ment causes  the  evaluation  of  one  or  more 
expressions,  Debug  displays  each  result  follow- 
ing the  statement.  The  result  is  preceded  by 
an  equal  sign. 

The  trace  function  is  local  to  the  current  pro- 
cedure. If  the  suspended  procedure  calls 
another  procedure,  Debug  suspends  the  trace 
function  until  control  returns  to  the  original 
procedure.  However,  once  you  turn  on  trace  for 
a  procedure,  it  continues  in  effect  until  you 
turn  it  off.  This  means  that  if  you  turn  trace 
on  in  a  called  procedure,  and  another  proce- 
dure subsequently  calls  it,  trace  continues  to 
display  the  called  procedure's  operations. 

Example:  tron  |  enter  | 
troff  I  ENTER  I 


When  Things  Go  Wrong 

Programming  errors  show  up  in  two  ways.  Either  your  procedure 
produces  incorrect  results,  or  it  terminates  prematurely. 
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In  the  first  instance,  you  can  stop  your  procedure  and  enter 
Debug  by  pressing  1  ctrl  |fc"|. 

However,  sometimes  your  program  executes  too  quickly  to  allow 
you  to  stop  it  at  the  appropriate  place.  In  this  case,  you  can  use 
the  Edit  mode  to  insert  a  MUSE  command  where  you  wish  the 
procedure  to  stop.  PAUSE  causes  the  procedure  to  halt  execution 
and  enter  the  Debug  mode. 

Once  in  Debug,  you  can  use  the  PRINT  command  to  examine 
the  procedure  variables.  \bu  can  use  LET  to  manipulate  the 
variable  values  to  determine  where  the  error  or  errors  occur.  Per- 
haps you  forgot  to  initialize  a  variable  or  forgot  to  increase  a  loop 
counter. 


Using  the  Trace  Function 

Sometimes,  errors  are  more  difficult  to  discover.  If  so,  the  next 
step  is  to  use  the  trace  function.  To  do  this,  type: 


tron  [ENTER 


Now  press  |  enter  |.  Each  time  you  press  I  enter  |,  Debug  executes 
one  line  of  the  procedure.  You.  can  see  the  original  source  state- 
ment, and  if  an  expression  is  evaluated,  Debug  prints  the  result 
of  the  expression,  preceded  by  an  equal  sign. 

In  this  manner,  you  can  step  through  the  entire  procedure,  or 
any  part  of  it,  examining  variable  values  as  you  go. 

What  About  Loops? 

The  STEP  command  is  helpful  if  you  find  yourself  tracing  the 
operation  of  a  loop.  Once  you  determine  that  the  loop  works  cor- 
rectly, you  can  avoid  tedious,  step-by-step  repetitions  by  turning 
trace  off  and  using  STEP  to  quickly  run  through  the  loop.  Then, 
turn  trace  back  on  and  resume  single-step  debugging.  For 
instance,  type: 


troff  I  ENTER  I 


step    200  lENTER  | 
tron  I  ENTER  I 
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In  Multiple  Procedures 

Although  the  trace  function  is  local  to  a  procedure,  you  can 
pause  and  turn  on  the  trace  function  in  as  many  procedures  as 
you  wish.  Trace  continues  to  operate  in  each  procedure  until  you 
turn  it  off  using  TROFF. 

To  cause  a  procedure  to  halt  execution  when  it  is  called  by 
another  procedure,  use  the  BREAK  command. 
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Data  and  Variables 


Data  Types 

Data  is  information  on  which  a  computer  performs  its  operations. 
Data  is  always  numeric  but,  depending  on  your  computer  appli- 
cation, it  can  represent  values,  symbols,  or  alphabetic  characters. 
This  means  that  the  same  items  of  physical  data  can  have  very 
different  logical  meanings,  depending  on  how  a  program  inter- 
prets it. 

For  instance,  65  can  represent: 

•  A  numeric  value  to  be  used  in  a  calculation. 

•  The  location  of  a  memory  address. 

•  The  offset  of  a  memory  location. 

•  The  two  character  symbols  6  and  5. 

•  The  character  A  in  the  ASCII  table.  ASCII  is  the  abbre- 
viation for  the  American  Standard  Code  for  Information 
Interchange. 

Because  of  the  differences  in  how  BASIC09  uses  data,  the  sys- 
tem lets  you  define  five  types  of  data.  For  instance,  there  are 
three  ways  to  represent  numbers.  Each  has  its  own  advantages 
and  disadvantages.  The  decision  to  use  one  way  or  another 
depends  on  the  specific  program  you  are  developing.  The  five 
BASIC09  data  types  are  byte,  integer,  real,  string,  and  Boolean. 

In  addition  to  the  preceding  data  types,  there  are  complex  data 
types  you  can  define.  The  manual  discusses  complex  data  struc- 
tures at  the  end  of  this  chapter. 

The  byte,  integer,  and  real  data  types  represent  numbers. 

The  string  data  type  represents  character  data  (alphabet,  punc- 
tuation, numeric  characters,  and  other  symbols).  The  default 
length  of  strings  is  32  characters.  Using  the  DIM  statement,  you 
can  specify  strings  of  both  longer  and  shorter  lengths. 

The  Boolean  data  type  represents  the  logical  value,  TRUE  or 
FALSE. 
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\bu  can  create  arrays  (lists)  of  any  of  these  data  types  with  one, 
two,  or  three  dimensions.  The  following  table  shows  the  data 
types  and  their  characteristics: 


Type 

Allowable  Values 

Memory 
Requirements 

BYTE 

Whole  numbers  (0  to  255) 

One  byte 

INTEGER 

Whole  numbers  (-32768 
to  32767) 

Two  bytes 

REAL 

Floating  point 

(±1*10a±S8) 

Five  bytes 

STRING 

Letters,  digits, 
punctuation 

One  byte  per 
character 

BOOLEAN 

True  or  false 

One  byte 

Real  numbers  appear  to  be  the  most  versatile.  They  have  the 
greatest  range  and  are  floating  point.  However,  arithmetic  opera- 
tions involving  real  numbers  execute  much  more  slowly  than 
those  involving  integer  or  byte  values.  Real  numbers  also  take 
up  considerably  more  memory  storage  space  than  the  other  two 
numeric  data  types. 

Arithmetic  involving  byte  values  is  not  appreciably  faster  than 
arithmetic  involving  integers,  but  byte  data  conserves  memory. 

If  you  do  not  specify  the  type  of  variable  (a  symbolic  name 
for  a  value)  in  a  DIM  statement,  BASIC09  assumes  the  vari- 
able is  real. 


The  Byte  Data  Type 

Byte  variables  hold  unsigned  eight-bit  data  (integers  in  the 
range  0  through  255).  Using  byte  values  in  computations, 
BASIC09  converts  the  byte  values  to  16-bit  integer  values.  If  you 
store  an  integer  value  that  is  too  large  for  the  byte  range, 
BASIC09  stores  only  the  least-significant  eight  bits  (a  value  of 
255  or  less),  and  does  not  return  an  error. 


6-2 


Data  and  Variables  I  6 


The  Integer  Data  Type 

Integer  variables  require  two  bytes  (16  bits)  of  storage.  They  can 
fall  in  the  range  -32768  to  32767.  If  a  calculation  involves  both 
integer  values  and  real  values,  BASIC09  presents  the  result  of 
the  calculation  as  a  real  number. 

Y)u  can  also  use  hexadecimal  values  in  integer  data.  To  do  so, 
precede  the  value  with  the  dollar  sign  ($).  For  instance,  to  repre- 
sent the  decimal  value  199  as  hexadecimal,  type  $C7.  The  hexa- 
decimal value  range  is  $0000  through  $FFFF. 

If  you  give  an  integer  variable  a  value  that  is  outside  the  integer 
range  (greater  than  32767  or  less  than  -32768),  BASIC09  does 
not  produce  an  error.  Instead  it  wraps  around  the  value  range. 
Fbr  instance,  the  calculation  32767  +  1  produces  a  result  of 
-32768. 

This  means  that  numeric  comparisons  made  on  values  in  the 
range  32768  through  65535  deal  with  negative  numbers.  You 
should  limit  such  comparisons  to  tests  for  equality  or  non- 
equality.  Functions  such  as  LAND,  LNOT,  LOR,  and  LXOR  use 
integer  values  but  produce  results  on  a  non-numeric,  bit-by-bit, 
basis. 

Division  of  an  integer  by  another  integer  yields  an  integer. 
BASIC09  discards  any  remainder. 


The  Real  Data  Type 

If  you  do  not  assign  a  data  type  to  a  variable,  BASIC09  assumes 
the  variable  is  real.  However,  programs  are  easier  to  understand 
if  you  define  all  variable  types. 

BASIC09  stores  as  real  values  any  constants  that  have  decimal 
points.  If  a  constant  does  not  have  a  decimal  point,  BASIC09 
stores  it  as  an  integer. 

BASIC09  requires  five  consecutive  memory  bytes  to  store  real 
numbers.  The  first  byte  is  the  exponent,  in  binary  two's  comple- 
ment. The  next  four  bytes  are  the  binary  sign  and  magnitude  of 
the  mantissa.  The  mantissa  is  in  the  first  31  bits;  the  sign  of 
the  mantissa  is  in  the  last  (least-significant)  bit  of  the  last  byte. 
The  following  illustration  shows  the  memory  storage  of  a  real 
number; 
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Internal  Representation  of  Real  Numbers 


exponent 

i                    i                    i 

mantissa 
i         i         i 

s 

byte:  0  12        3        4 

The  exponent  covers  the  range  2.938735877x10  "39  (2"128) 
through  1.701411835xl038  (2127)  as  powers  of  2.  Operations  that 
result  in  values  out  of  the  representation  range  cause  an  over- 
flow or  underflow  error.  You  can  handle  such  errors  using  the  ON 
ERROR  command. 

The  mantissa  covers  the  range  0.5  through  .9999999995  in  steps 
of  2-31.  This  means  that  real  numbers  can  represent  values 
.0000000005  apart.  BASIC09  rounds,  operation  values  that  fall 
between  these  points  to  the  nearest  point. 

Because  floating  point  arithmetic  is  inherently  inexact,  a 
sequence  of  operations  can  produce  a  cumulative  error.  Proper 
rounding,  as  implemented  in  BASIC09,  reduces  the  effect  of  this 
problem,  but  cannot  eliminate  it.  When  using  real  quantities  in 
comparisons,  be  sure  your  computations  can  produce  the  exact 
value  you  desire. 

String  Variables 

A  string  is  a  variable-length  sequence  of  ASCII  values.  The 
length  can  vary  from  0,  a  null  string,  to  the  capacity  of  the 
memory  available  to  BASIC09. 

You  can  define  a  string  variable  either  explicitly,  using  the  DIM 
statement,  or  implicitly  by  appending  the  dollar  sign  ($)  to  the 
variable  identifier  (variable  name).  For  example,  title$  implicitly 
identifies  a  string  variable. 

Unless  you  specify  otherwise,  BASIC09  assigns  a  maximum 
string  length  of  32  characters.  Using  the  DIM  statement,  you 
can  specify  a  maximum  length  either  less  than  or  greater  than 
32.  To  conserve  memory,  use  DIM  to  assign  only  the  maximum 
length  you  need  for  any  string  variable. 

The  beginning  of  a  string  is  always  Character  1.  The  BASE 

statement,  which  sets  numeric  variable  base  numbers  as  either  0 
or  1,  does  not  affect  string  variables. 
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If  an  operation  results  in  a  string  too  long  to  fit  in  the  assigned 
maximum  storage  space,  the  system  truncates  the  string  on  the 
right.  It  does  not  produce  an  error. 

String  storage  is  fixed  at  the  dimensioned  length.  The  sequence 
of  actual  string  byte  values  is  terminated  by  the  value  of  zero,  or 
by  the  maximum  length  allotted  to  the  string.  Any  unused  stor- 
age after  the  zero  byte  allows  the  stored  string  to  expand  and 
contract  within  its  assigned  length. 

The  following  example  shows  the  internal  storage  of  a  variable 
dimensioned  as  string  [6]  and  assigned  the  value  "SAM". 
Note  that  Byte  3  contains  the  string  terminator  00.  The  string 
does  not  use  bytes  following  00. 


s 

A 

M 

00 

byte: 


6 


If  you  assign  the  value  "ROBERT"  to  the  variable,  BASIC09  does 
not  need  to  terminate  the  string  with  00  because  the  string  is 
full: 


byte: 


R 

O 

B 

E 

R 

T 

6 


The  way  BASIC09  handles  string  storage  is  important  when  you 
write  programs.  If  you  do  not  specify  a  length  for  strings  you 
define,  the  system  uses  the  default  length  32.  As  you  can  see, 
this  wastes  computer  memory  if  you  store  strings  of  only  four  or 
five  characters. 


The  Boolean  Type 

A  Boolean  operation  always  returns  either  the  character  string 
"TRUE"  or  "FALSE".  You  cannot  use  the  Boolean  data  type  for 
numeric  computation — only  for  comparison  logic. 

Do  not  confuse  the  Boolean  operations  AND,  OR,  XOR,  and  NOT 
(which  operate  on  the  Boolean  values  TRUE  and  FALSE)  with 
the  logical  functions  LAND,  LOR,  LXOR,  and  LNOT  (which  use 
integer  values  to  produce  numeric  results  on  a  bit-by-bit  basis). 
An  attempt  to  store  a  non-Boolean  value  in  a  Boolean  variable, 
causes  an  error. 
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Automatic  Type  Conversion 

When  an  operation  mixes  numeric  data  types  (byte,  integer,  or 
real  values),  BASIC09  automatically  and  temporarily  converts 
the  values  to  the  type  necessary  to  retain  accuracy.  This  conver- 
sion lets  you  use  numeric  quantities  of  mixed  types  in  most 
calculations. 

The  system  returns  a  type-mismatch  error  when  an  expression 
includes  types  that  cannot  legally  mix.  These  errors  are  reported 
by  the  second  compiler  pass,  which  occurs  automatically  when 
you  exit  the  edit  mode. 

Because  type  conversion  takes  additional  execution  time,  you  can 
speed  calculations  by  using  values  of  a  single  type. 

Constants 

Constants  are  values  in  a  program  that  do  not  change.  They  can 
use  any  of  the  five  data  types.  The  following  are  examples  of  con- 
stants in  a  procedure: 

HDME$-"Fort  Worth" 

VALUE»-"$2S,000 

VALUE=25 

PAYMENT*99.99 

ANSWER-"TRUE" 

MEMORY=$aCFF 

PRINT  "The  End" 

Numeric  constants  are  either  integers  or  real  numbers.  If  a 
numeric  constant  includes  a  decimal  point  or  uses  the  "E  format" 
exponential  form,  it  causes  BASIC09  to  store  the  number  in  the 
real  format,  even  if  it  could  store  the  number  in  integer  or  byte 
format. 

You  can  use  this  feature  to  force  a  real  format.  For  instance,  to 
make  the  number  12  a  real  number,  type  it  as  12.0.  You  might 
want  to  force  real  values  in  this  way  when  all  other  values  in  an 
expression  are  real  so  that  BASIC09  does  not  have  to  do  a  time- 
consuming  type  conversion  at  run  time. 


6-8 


Data  and  Variables  I  6 


BASIC09  also  stores  as  real  numbers  any  numbers  that  do  not 
have  decimal  points  but  that  are  too  large  to  store  as  integers. 
Here  are  some  examples  of  legal  real  constants: 


1.0 

9.8433218 

-.01 

-999.000099 

100000000 

5644.34532 

1.95E  +  12 

-99999.9E-33 

BASIC09  treats  numbers  that  do  not  have  a  decimal  point  and 
are  in  the  range  -32768  through  +  32767  as  integers.  You  must 
always  precede  hexadecimal  numbers  with  a  dollar  sign. 

Following  are  examples  of  legal  integer  constants: 


12 

-3000 

55 

$20 

$FF 

$09 

0 

-12 

-32768 

String  Constants 

A  string  constant  consists  of  a  sequence  of  characters  enclosed  in 
double  quotation  marks,  such  as: 

"The   End" 

To  place  a  string  constant  in  a  string  type  variable,  use  the 
equal  symbol  in  this  manner: 

TITLES  =  "Masters  Of  Magic" 

To  include  double  quotation  marks  within  a  string,  use  two  sets 
of  double  quotation  marks,  like  this: 

"fin    ""older   man""    is    wiser." 

A  string  can  contain  characters  that  have  ASCII  values  in  the 
range  0  through  255. 

Variables 

In  BASIC09,  a  variable  is  local  to  the  procedure  in  which  it  is 
defined.  A  variable  defined  in  one  procedure  has  no  meaning  in 
another  procedure  unless  you  use  the  RUN  and  PARAM  state- 
ments to  pass  the  variable  when  you  call  the  other  procedure. 

The  local  nature  of  variables  lets  you  use  the  same  variable 
name  in  more  than  one  procedure  and,  unless  you  specify  other- 
wise, have  the  variables  operate  independently  of  each  other. 
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You  can  assign  variables  using  either  the  LET  statement  with 
the  assign  symbol  ( = ),  or  by  using  the  assign  symbol  alone.  For 
instance,  both  the  following  command  lines  are  legal: 

LET  PAYMENTM4.S0 

PAYMENT" 4 4. 50 

When  you  call  a  procedure,  BASIC09  allocates  storage  for  the 
procedure's  variables.  It  is  not  possible  to  force  a  variable  to 
occupy  an  absolute  address  in  memory.  When  you  exit  a  proce- 
dure, the  system  returns  the  storage  allotted  for  variables,  and 
you  lose  the  stored  values. 

If  you  write  a  procedure  to  call  itself  (a  recursive  procedure),  the 
call  creates  separate  storage  space  for  variables. 

Note:  Unlike  other  BASICS,  BASIC09  does  not  automati- 
cally initialize  variables  by  setting  them  to  zero.  When  you 
execute  a  procedure,  all  variables,  arrays,  and  structures 
have  random  values.  Your  procedure  must  initialize  the 
variables  you  specify  to  the  values  you  require. 

Passing  \ariables 

When  one  procedure  passes  variable  values  to  another  procedure, 
BASIC09  refers  to  the  passed  variables  as  parameters.  You  can 
pass  variables  either  by  reference  or  by  value. 

BASIC09  does  not  protect  variables  passed  by  reference.  There- 
fore, the  called  procedure  can  change  the  values  and  return  the 
new  values.  BASIC09  does  protect  variables  passed  by  value,  so, 
the  called  program  cannot  change  them. 

To  pass  a  parameter  by  reference,  enclose  the  name  of  the  vari- 
able in  parentheses  as  part  of  the  RUN  statement  in  this 
manner: 

RUN  RANDOM<10>      passes  the  value  10  to  a  procedure 
called  Random 

The  system  evaluates  the  storage  address  of  each  passed  vari- 
able, and  sends  the  variable  to  the  called  procedure.  The  called 
procedure  associates  the  storage  addresses  with  the  names  in  its 
local  PARAM  statement.  It  then  uses  the  storage  area  as  though 
it  had  created  it  locally.  This  means  it  can  change  the  value  of 
the  parameter  before  returning  it  to  the  calling  procedure. 
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To  pass  parameters  by  value,  write  the  value  to  be  passed  as  an 
expression.  BASIC09  evaluates  the  expression  at  the  time  of  the 
call.  To  use  a  variable  in  an  expression  without  changing  its 
value,  use  null  constants,  such  as  0  for  a  number  or  ""  for  a 
string,  in  this  manner: 

RUN  ADDCOLUMN(x  +  0)  passes  the  value  of  x  by 

value 
run  translatecw$  +  m,,j  passes  the  contents  of  w$  by 

value 

To  pass  parameters  by  value,  BASIC09  creates  a  temporary  vari- 
able. It  places  the  result  of  the  expression  in  the  temporary  vari- 
able and  sends  the  address  to  the  called  procedure.  This  means 
that  the  value  given  to  the  called  procedure  is  a  copy  of  the 
result  of  the  expression,  and  the  called  procedure  cannot  change 
the  original  value. 

The  results  of  expressions  containing  numeric  constants  are 
either  integer  or  real  values;  there  are  no  byte  constants.  To 
send  byte-type  variables  to  a  procedure,  pass  the  values  by  refer- 
ence. Therefore,  if  a  RUN  statement  evaluates  an  integer  as  a 
parameter  and  sends  it  to  a  byte-type  variable,  the  byte  variable 
uses  only  the  high-order  byte  of  the  two-byte  integer. 

Arrays 

An  array  is  a  group  of  related  data  values  stored  consecutively 
in  memory.  The  system  knows  the  entire  group  by  a  variable 
name.  Each  data  value  is  an  element.  You  use  a  subscript  to  refer 
to  any  element  of  the  array.  For  example,  an  array  named  Graf 
might  contain  five  elements  referred  to  as: 

GRAF(t)         GRAFC2)         GRAFC3>         GRAF<4>         GRAF<S> 

You  can  use  each  of  these  elements  to  store  a  different  value, 
such  as: 

GRAF<1)  •  25 

GRAFC2>  -  47 

GRAFC3)  ■  39 

GRAF(4>  =  18 

GRAFC5)  =  50 
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Note:  Normally,  array  elements  start  with  1  in  BASIC09. 
However,  you  can  use  the  BASE  command  to  cause  array 
elements  to  begin  at  0. 

The  previous  example  illustrates  a  single-dimensioned  array.  The 
elements  are  arranged  in  one  row  and  only  one  subscript  is  used 
for  each  element. 

The  following  procedure  lets  you  type  values  for  a  GRAF  array, 
and  displays  the  results  in  a  simple  graph. 

PROCEDURE   GRAF 

□DIM    GRAF(S):REAL 

□SHELL   "DISPLAY    0C" 

□FOR   T-1    TD    5 

□PRINT   "Value    for    Item   #";    T;    "□" j 

□INPUT   GRAFCt) 

□NEXT    T 

DPRINT 

□PRINT 

□PRINT   "This    is    how   your    graph    stacks    up..." 

□PRINT 

□FOR    T=1    TO    5 

DPRINT   "Item   #";    T;    "L"\ 

□FOR   U-1    TO   GRAFCT) 

□PRINT    CHR$(79); 

□NEXT    U 

□PRINT 

□NEXT    T 

□PRINT 

□END 

This  program  uses  a  single  dimension  array — in  effect,  a  list. 

You  can  also  create  arrays  with  more  than  one  dimension  — 
more  than  one  element  for  each  row.  You  might  use  a  two-dimen- 
sioned array  in  a  program  to  store  names  and  addresses.  Instead 
of  creating  separate  arrays  for  the  name,  address,  and  zip  code, 
you  could  set  up  one  array  with  two  dimensions. 
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The  following  program,  used  to  enter  the  names  of  a  company's 
employees,  shows  how  this  might  be  done.  See  the  second  line  for 
the  DIM  syntax.  When  you  run  the  procedure,  it  asks  you  for  a 
name,  address,  and  zip  code  for  each  of  10  employees.  After  you 
type  the  information  for  all  the  entries,  the  procedure  displays 
the  information  on  the  screen. 

PROCEDURE  Names 

QDIM  NAMEd 0,3>:STRING 

DSHELL  "DISPLAY  0C" 

DBASE  0 

CFOR  T  =  0  TO  9 

DPR  I  NT  "Type  Employee  Name  No.";  T;  ":  " ; 

DINPUT  NAMECT.0) 

DPRINT  "Type  Employee  Address  No.";  T;  " :  " ; 

DINPUT  NAME(T,1> 

DPRINT  "Type  Employee  Zip  Code  No.";  T;  ":  "j 

DINPUT  NAMEd, 2> 

UNEXT  T 

CSHELL  "DISPLAY  0C" 

CPRINT  "And  the  names  are..." 

DPRINT 

DFOR  T=0  TO  9 

DPRINT  NAMEd, 0>;  "D" ;  NAMEd, 1);  "I";  NAMEd, 2) 

DNEXT  T 

DEND 

The  DIM  statement  reserves  space  in  memory  for  a  string  array 
named  Name,  with  two  dimensions.  As  you  enter  data,  the  Name 
field  is  Stored  in  NameCB  ,0),  Named  ,0),  Name(2,0>,  and  so  on. 
The  Address  field  is  stored  in  Name  <  8,1),  NameCl,l), 
Neme(2,l),  and  so  on.  The  Zip  field  is  stored  in  Name<0,2>, 
Named  ,2),  Name (2, 2),  and  so  on.  This  continues  until  you  fill 
the  grid,  10  entries  with  three  items  each. . 

You  can  also  create  arrays  with  three  dimensions.  The  following 
program  adds  one  more  dimension  that  keeps  track  of  each 
employee's  company.  It  dimensions  Name$  as  Name $(2,1  0  ,3). 
The  first  dimension  contains  either  0  or  1  to  indicate  to  which 
company  the  employee  belongs. 
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PROCEDURE  names2 

DDIM  NAME$(2,10,3>:STRING 

DSHELL  "DISPLAY  0C" 

DBASE  0 

DFOR  X-0  TO  1 

DPR  I  NT 

DPR  I  NT 

CFDR  T  =  0  TD  9 

CPRINT 

jIF  X-0  THEN 

3PRINT  "Type  a  Wiggleworth  Company  employee 

nome ..." 

DELSE 

DPR1NT  "Type  a  Putforth  Compati'.'  employee  name..." 

DENDIF 

CPRINT  "Type  Name  No.";  T;  " :  " ; 

CINPUT  NAMES<X,T,0> 

DPR  I  NT  "Type  Address  No.";  T;  " :  "j 

DINPUT  NAME$CX,T,1 ) 

DPRINT  "Type  Zip  Code  No.";  T;  ":  "; 

DINPUT    NAME$(X,T,2> 

DNEXT   T 

DNEXT    X 

CSHELL  "DISPLAY  0C" 

CPRINT  "The  Wiggleworth  employees  are..." 

jPRINT 

DX-0 

DFOR  T=0  TO  9 

DPRINT  NAME$CX,T,0);  "CI";  NAME$< X , T , 1 ) ;  "D" j 

NAME$CX,T,2) 

DNEXT  T 

SPRINT 

JPRINT  "The  Putforth  Company  employees  are..." 

GPRINT 

DX  =  1 

DFOR  T-0  TO  9 

CPRINT  NAME«CX,T,0);  "D" j  NAMESC X ,T,  1  )  ;  "D" J 

NAME$(X,T,2) 

CNEXT  T 

DEND 
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The  easiest  way  to  understand  three  dimensional  arrays  is  to 
consider  the  first  dimension  as  a  page.  In  other  words,  if  the  first 
dimension  in  the  string  is  0,  the  employee  is  on  the  Wiggleworth 
Company's  page.  If  the  first  dimension  in  the  string  is  1,  the 
employee  is  on  the  Putforth  Company's  page. 

Complex  Data  Types 

In  addition  to  the  five  standard  data  types,  you  can  create  your 
own  data  types.  Using  the  TYPE  command,  you  can  define  a 
new  data  type  as  a  vector  (a  single-dimensioned  array)  of  any 
previously  defined  type. 

For  example,  in  the  previous  program,  the  Name  variable  can 
contain  only  one  type  of  data,  the  string  type.  However,  using 
the  TYPE  command  you  can  create  a  variable  that  accepts  sev- 
eral data  types. 

Suppose  you  create  an  employee  list  procedure  that  uses  the  fol- 
lowing variables,  of  the  following  size  and  types: 

Name      Length    Contents Type 

employee  name  string 

street  address  string 

city  of  address  string 

address  zip  code  integer 

false  =  male,  true  =  female  Boolean 

employee  age  byte 

You  can  combine  all  these  variables  into  one  complex  data  type. 
To  do  so,  dimension  the  variables  within  a  TYPE  command  line, 
like  this: 

TYPE    EMPL0YEE-NAP1E:STRING[2S];    STREET: STRINGE20] ; 
CITY:STRINGMB);    ZIP:REAL;    SEX  :B00LEAN ;    AGE:BYTE 

This  creates  a  new  BASIC09  type,  called  Employee.  Employee 
requires  its  variables  to  have  six  fields  of  the  name,  size,  and 
type  shown  in  the  previous  chart. 

Once  you  create  the  new  data  type,  you  can  define  variables  to 
use  it.  For  instance,  the  following  program  line  defines  Worker  as 
type  employee,  with  10  elements  in  the  array: 

ID  I  PI   W0RKERC1  0):EPIPLQYEE 
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Street 

20 

City 

10 

Zip 

— 

Sex 

— 

Age 

— 
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To  put  the  employee  data  type  to  work,  collect  your  data  with 
INPUT  commands.  Then,  store  the  data  into  the  new  Worker 
array.  The  following  program  demonstrates  how  you  might  do 
this: 

PROCEDURE  worker 

DREM  Dimension  variables  for  input 

ODIM  NM:STRINGt2S] 

DDIM  ST:STRINGt20J 

DDIM  CTY:STRINGM0] 

DDIM  ZP:R£AL 

DDIM  SX:B00LEAN 

DDIM  AG  .-BYTE 

DREM         Create  new  type  and  array  using  new 

type 

DTYPE  EMPLOYEE-NAME: STRINGt2S];  STREET ; STR I NGC20 ] ; 

CITY:STRINGC10  ]j  ZIP:REAL;  SEX:BO0LEAN;  AGE:BYTE 

DDIM  WORKERC10):EMPLOYEE 

DREM 

DFOR  T-1  TO  10 

HINPUT  "Name:G",NM 

DINPUT  "Street :3" , ST 

DINPUT  "CltyiC'.CTY 

C INPUT  "Zip:D",ZP 

DINPUT  "Sex:D",SX 

DINPUT  "Age:D" ,AG 

DREM        Store  Input  in  the  Worker  nrray  using 

field  names 

DWORKERCT). NAME=NM 

DWORKERCT). STREET- ST 

DWORKERCT). CITY-CTY 

0W0RKER(T).ZIP=ZP 

OWORKERCT).SEX*SX 

DWORKERCT). AGE-AG 

DPRINT 

DPR  INT  "*  *»»»»«»***»****»»#  *" 

DPRINT 

DNEXT  T 

DSHELL  "DISPLAY  COO" 

DPRINT  "The  names  in  your  files  now  are..." 

DPRINT 

DFOR  T-1  TO  10 

DPRINT  WORKERCT).NAME 

DPRINT  WORKERCT). STREET 

DPRINT  WORKERCT). CITY 
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DPRINT   WORKERCD.ZIP 

JIF    WORKER(T>.SEX=TRUE 

DTHEN   PRINT   "Female" 

GELSE 

CPRINT    "Male" 

DENDIF 

DPRINT   WORKER(T).AGE 

DPRINT 

DPRINT  "********»«*»*****»**" 

DPRINT 

UNEXT    T 

Note  that  the  Sex  field  is  defined  as  Boolean.  This  means  that 
you  can  respond  only  in  two  ways,  TRUE  or  FALSE.  The  method 
of  input  requires  only  one  byte  of  storage.  To  use  this  data  you 
need  to  handle  it  so  TRUE  and  FALSE  indicate  female  and  male. 

Complex  data  types  can  contain  more  than  one  field.  Each  field 
can  be  of  any  data  type.  You  reference  the  fields  of  a  complex 
data  type  by  typing  the  variable  name,  its  array  index,  a  period 
{.),  and  the  field  name.  The  following  lines,  from  the  Worker  pro- 
cedure, show  how  BASIC09  stores  the  data  from  the  input  lines 
into  the  Worker  variable: 

WORKERCTJ.NAME-NM 

WORKERCT).STREET-ST 

WORKERCT).CITY=CTY 

WORKER(T).ZIP-ZP 

WORKERCT>.SEX-SX 

WORKERCT>.AGE-AG 

These  lines  store  the  values  in  the  variables  NM,  ST,  CTY,  ZP, 
SX,  and  AG  into  the  NAME,  STREET,  CITY,  ZIP,  SEX,  and 
AGE  fields  of  the  Worker  variable.  This  operation  is  within  a 
FOR/NEXT  loop  that  uses  T  as  a  counter.  In  the  procedure,  T 
can  refer  to  a  value  in  the  range  1  to  10. 

The  procedure  uses  the  same  type  of  operation  to  extract  the 
data  from  the  complex  data  type  variable: 
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PRINT  WORKERCT). NAME 

PRINT  WORKERCT). STREET 

PRINT  WORKERCT). CITY 

PRINT  WORKER(T>.ZIP 

IF  WORKERCT). SEX=TRUE  THEN  PRINT  "Female" 

ELSE  PRINT  "Male" 

ENDIF 

PRINT  WORKERCT). AGE 

Using  the  same  methods,  you  can  create  complex  data  types  that 
combine  other  complex  data  types  and  standard  data  types. 

The  elements  of  a  complex  structure  can  be  copied  to  another 
similar  structure.  Using  a  single  assignment  operator,  you  can 
write  an  entire  structure  to,  or  read  an  entire  structure  from, 
mass  storage  as  a  single  entity.  For  example: 

PUT  #2,  WORKERCT) 

Because  the  system  defines  the  elements  of  complex-type  storage 
during  compilation,  it  need  not  do  so  during  runtime.  This 
means  that  BASIC09  can  reference  complex  structure  faster  than 
it  can  reference  arrays. 
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Expressions,  Operators,  and 
Functions 


Manipulating  Data 

BASIC09  uses  expressions  to  manipulate  data.  (Expressions  are 
pieces  of  data  connected  by  operators.) 

An  operator  is  a  symbol  or  a  word  that  signifies  some  action  to 
be  performed  on  the  specified  data.  Each  data  item  is  a  value. 


Expressions 

When  an  expression  is  evaluated,  the  result  is  a  value  of  some 
data  type  (real,  integer,  string,  byte,  or  Boolean). 

An  expression  might  look  like  this: 


First          First 
Value      Operator 

Second 
Value 

Second 

Operator 

Result 

6                + 

5 

= 

11 

or  like  this: 

First          First 
Value      Operator 

Second 
Value 

Second 
Operator 

Result 

"Seaside"          + 

"Villa" 

= 

Seaside 
Villa 

When  BASIC09  evaluates  an  expression,  it  copies  each  value  onto 
an  expression  stack.  Functions  and  operators  take  their  input 
values  from  this  stack  and  return  their  results  to  it.  Many 
expressions  result  in  assignments,  as  do  the  examples  shown. 
The  BASIC09  makes  the  resulting  assignment  only  after  it  com- 
putes the  entire  expression.  This  lets  you  use  the  variable  that  is 
being  modified  as  one  of  the  values  in  the  expression,  such  as  in 
this  example: 

X-X  +  1 
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The  result  of  an  expression  is  always  one  of  the  five  BASIC09 
data  types.  However,  you  can  often  mix  data  types  within  an 
expression  and,  in  some  cases,  the  result  of  an  expression  is  of  a 
different  data  type  than  any  of  the  values  in  the  expression. 
Such  is  the  case  if  you  use  the  kss-than  symbol  (<),  in  this 
manner: 

24    <    100 

The  less-than  operator  compares  two  integer  values.  The  result 
of  the  comparison  is  Boolean;  in  this  case,  the  value  is  TRUE. 


Type  Conversion 

Because  BASIC09  performs  automatic  type  conversion  of  values, 
you  can  mix  any  of  the  three  numeric  data  types  in  an  expres- 
sion. When  you  mix  numeric  data  types,  the  result  is  always  of 
the  same  type  as  the  value  having  the  largest  representation,  in 
this  order:  real  <  integer  <  byte. 

You  can  use  any  numeric  type  in  an  expression  that  produces  a 
real  number.  If  you  want  an  expression  to  produce  a  byte  or  inte- 
ger type  value,  the  result  must  be  small  enough  to  fit  the 
desired  type. 

Operators 

BASIC09  has  operators  to  deal  with  all  types  of  data.  Each  oper- 
ator, except  NOT  and  negation  (unary  -),  takes  two  values  or 
operands,  and  performs  an  operation  to  produce  a  result.  NOT 
can  accept  only  one  value.  The  following  table  lists  the  operators 
available  and  the  types  of  data  they  accept  and  produce. 

Because  the  same  operators  function  on  the  three  types  of 
numeric  data  (byte,  integer,  and  real),  these  types  are  referred  to 
by  the  operand  type  "numeric." 
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BASIC09  Expression  Operators 


Operand 

Result 

Operator 

Function 

Type 

Type 

— 

Negation 

numeric 

numeric 

-  or  ** 

Exponentiation 

numeric 

numeric 

* 

Multiplication 

numeric 

numeric 

/ 

Division 

numeric 

numeric 

+ 

Addition 

numeric 

numeric 

- 

Subtraction 

numeric 

numeric 

NOT 

Logical  Negation 

Boolean 

Boolean 

AND 

Logical  AND 

Boolean 

Boolean 

OR 

Logical  OR 

Boolean 

Boolean 

XOR 

Logical  Exclusive  OR 

Boolean 

Boolean 

+ 

Concatenation 

string 

string 

= 

Equal  to 

all  types 

Boolean 

<>  or 

>< 

Not  equal  to 

all  types 

Boolean 

< 

Less  than 

numeric, 

stringf 

Boolean 

<=  or 

=  < 

Less  than  or  equal 

numeric, 

string! 

Boolean 

> 

Greater  than 

numeric, 

stringt 

Boolean 

>=  or 

=  > 

Greater  than  or  equal 

numeric, 

stringt 

Boolean 

t  When 

comparing  strings,  BASIC09  uses  the  ASCII  values  of 

characters  as  the  basis  for  comparison.  Therefore,  0  <  1,  9  <  A, 

A<B, 

A< 

'.  b,  b  <  z,  and  so  on. 

Arithmetic  Operators 

Arithmetic  operators  perform  operations  on  numeric  data.  There- 
fore, both  operands  in  the  expression  must  be  numeric.  The  fol- 
lowing table  lists  the  arithmetic  operators. 

Negation 
Exponentiation 


Multiplication 


Division 


The  single  dash  negates  a  number's  sign: 
-10  is  negative  10. 

Use  a  caret  (")  or  two  asterisks  (**)  to  raise 
a  number  to  a  power;  2*3  is  8  (2  x  2  x  2). 
Similarly,  2**3  is  8. 

A  single  asterisk  causes  multiplication; 
2  *  3  is  6. 

A  slash  causes  division:  6  /  2  is  3. 
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Addition  The  plus  sign  causes  addition:  3  +  3  is  6. 

Subtraction  A  dash  causes  subtraction:  6  -  3  is  2. 


Hierarchy  of  Operators 

BASIC09  uses  the  standard  hierarchy  of  operations  when  calcu- 
lating expressions  with  multiple  operators.  This  means  that 
BASIC09  has  an  order  in  which  it  performs  calculations  involv- 
ing more  than  one  operator. 

The  following  BASIC09  operators  are  listed  in  order  of 
precedence: 


NOT 

** 

(negate) 

* 

+ 
> 

AND 
OR 

<     <>     = 

XOR 

Also 

i,  BASIC09: 

<  = 


•  Performs  operations  enclosed  in  parentheses  before  oper- 
ations not  in  parentheses. 

•  Performs  the  leftmost  operations  first  when  two  or  more 
operations  are  of  equal  precedence. 

"You  can  use  parentheses  to  override  this  standard  precedence. 
For  example: 

2    ♦    1     *    3    =    5 

but 

i    2    +    1     )    »    3    -    9 

The  following  examples  show  BASIC09  expressions  on  the  left, 
and  the  way  BASIC09  evaluates  them  on  the  right.  %u  can 
enter  the  expressions  in  either  form,  but  the  decompiler  gener- 
ates the  simpler  form,  shown  on  the  left. 
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BASIC09 
Representation 


Equivalent 
Form 


a  =  b  +  c**2/d 


a  =  b  +  ((c**2)/d) 


a  =  b>c   AND   d>e  OR     a  =  {(b>c)  AND  (d>e)) 
c  =  e  OR(e  =  e) 


a=(b  +  c  +  d)/e 
a  =  b**c**d/e 
a=  -(b)**2 
a  =  b  =  c 


a=((b  +  c)+d)/e 
a  =  (b**(c**d))/e 
a  =  (-b)**2 
a  =  (b  =  c) 


Relational  Operators 

Relational  operators  make  logical  comparisons  of  any  type  of  data 
and  return  a  result  of  either  TRUE  or  FALSE.  An  explanation  of 
the  relational  operators  follows.  All  relational  operators  have 
equal  precedence. 

=  Equal.  Returns  TRUE  if  both  operands  are 

equal,  or  FALSE  if  they  are  not  equal. 

<  Less  than:  Returns  TRUE  if  the  first  operand  is 
less  than  the  second,  or  FALSE  if  is  not. 

>  Greater  than:  Returns  TRUE  if  the  first  operand 
is  greater  than  the  second,  or  FALSE  if  it  is  not. 

<>  or  ><        Unequal:  Returns  TRUE  if  the  operands  are  not 
equal  or  FALSE  if  they  are. 

<  =  or  =  <       Less  than  or  equal  to:  Returns  TRUE  if  the  first 

operand  is  less  than  or  equal  to  the  second 
operand.  Otherwise,  the  operation  returns 
FALSE. 

>  =  or  =  >       Greater  than  or  equal  to:  Returns  TRUE  if  the 

first  operand  is  greater  than  or  equal  to  the 
second.  Otherwise,  the  operation  returns  FALSE. 
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Ibu  normally  use  relational  operators  in  IF/THEN  statements. 
For  example,  if  your  procedure  has  two  numeric  variables,  Pay- 
ments and  Income,  you  might  include  command  lines  like  this: 

IF  PAYMENTS  >  INCOME  THEN 

PRINT  "You're  Broke!" 
ENDIF 

When  you  combine  arithmetic  and  relational  operators  in  the 
same  expression,  BASIC09  evaluates  the  arithmetic  operations 
first.  For  example: 

IF    X*Y/2    <=    14   THEN 

PRINT  "Average  Score  is  ";  X*Y/2 

ENDIF 

BASIC09  performs  the  arithmetic  operation  x*y/2,  then  compares 
the  result  with  the  value  14. 

When  you  use  relational  operators  with  strings,  BASIC09  com- 
pares the  strings  character  by  character.  When  it  finds  two  char- 
acters that  do  not  match,  it  checks  to  see  which  character  has 
the  lower  ASCII  code  value.  The  string  containing  the  character 
with  the  lower  value  comes  first. 

Consider  this  example: 

PRINT   "hunt"   >   "hung" 

BASIC09  compares  each  character  in  each  string.  Because  the 
first  three  characters  are  the  same,  the  result  of  the  operation  is 
based  on  the  comparison  of  t  and  g.  Because  t  (ASCII  value  = 
116)  is  "greater  than"  g  (ASCII  value  =  103),  the  command 
prints  TRUE. 


String  Operators 

The  string  operator  is  the  plus  sign  (  +  ).  This  symbol  appends 
one  string  to  another.  All  operands  must  be  strings,  and  the 
resulting  value  is  one  string.  Examine,  for  example,  the  follow- 
ing line,  which  appends  three  strings: 

PRINT   "My   friends    are    "    ♦    "Jack    and    "    +    "Jill." 

It  prints:  My    friends    are    Jack    and    Jill. 
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Logical  Operators 

The  logical,  or  Boolean,  operators  make  logical  comparisons  of 
Boolean  values.  The  following  table  describes  the  results  yielded 
by  each  logical  operator  given  the  specified  TRUE/FALSE  values: 

Meaning  of  First         Second 

Operator  Operation  Operand     Operand      Result 


NOT  The  result  is  the  opposite  of  TRUE 

the  operand.  FALSE 

AND         When  both  values  are  TRUE,  TRUE 
the  result  is  TRUE.  TRUE 

Otherwise,  the  result  is  FALSE 

FALSE.  FALSE 

OR  When  both  values  are  TRUE 

FALSE,  the  result  is  FALSE.  TRUE 
Otherwise,  the  result  is  FALSE 

TRUE.  FALSE 

XOR  When  only  one  of  the  values  TRUE 

is  TRUE,  the  result  is  TRUE 

TRUE.  Otherwise  the  result  FALSE 
is  FALSE.  FALSE 


FALSE 

TRUE 

TRUE 

TRUE 

FALSE 

FALSE 

TRUE 

FALSE 

FALSE 

FALSE 

TRUE 

TRUE 

FALSE 

TRUE 

TRUE 

TRUE 

FALSE 

FALSE 

TRUE 

FALSE 

FALSE 

TRUE 

TRUE 

TRUE 

FALSE 

FALSE 

Use  logical  operators  in  IF/THEN  statements  such  as: 

IF  PAYMENTS  <  INCOME  AND  INCOME+SAVINGS  > 
PAYMENTS  THEN 

PRINT  "You'll  have  to  use  your  savings  to  get 
out  of  this  mess." 

ENDIF 


Functions 

Functions  are  operation  sequences  the  system  performs  on  data. 
In  a  statement,  BASIC09  performs  functions  first.  Chapter  11, 
"Command  Reference,"  describes  the  following  functions. 
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Functions  returning  results  of  type  real 


SIN  Calculates  the  trigonometric  sine  of  a  number, 

COS  Calculates  the  trigonometric  cosine  of  a  number. 

TAN  Calculates  the  trigonometric  tangent  of  a  number. 

ASN  Calculates  the  trigonometric  arcsine  of  a  number. 

ACS  Calculates  the  trigonometric  arccosine  of  a  number. 

ATN  Calculates  the  trigonometric  arctangent  of  a 

number. 

LOG  Calculates  the  natural  logarithm  (base  e)  of  a 

number. 

LOG10         Calculates  the  logarithm  (base  10)  of  a  number. 

EXP  Calculates  e  (2.71828183)  raised  to  the  specified 

positive  power. 

FLOAT         Converts  byte  or  integer  type  numbers  to  real 
numbers. 

INT  Calculates  the  largest  whole  number  less  than  or 

equal  to  the  specified  number. 

PI  Represents  the  constant  3.14159265. 

SQR  Calculates  the  square  root  of  a  positive  number. 

SQRT  Calculates  the  square  root  of  a  positive  number.  Its 

function  is  identical  to  SQR. 

RND  Returns  a  random  number. 
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Functions  returning  results  of  any  numeric  type 

The  resulting  type  depends  on  the  input  type. 


ABS  Calculates  the  absolute  value  of  a  number, 

SGN  Returns  a  value  to  indicate  the  sign  of  the  specified 

number  (-1  if  the  number  is  less  than  0,  0  if  the 
number  is  0,  or  1  if  the  number  is  greater  than  0). 

SQ  Calculates  the  square  of  a  number. 

YAL  Converts  a  string  to  a  numeric  value. 

Functions  returning  results  of  type  integer  or  type  byte 

FIX  Rounds  a  real  number  and  converts  it  to  an 

integer. 

MOD  Calculates  the  modulus  (remainder)  of  two 

numbers. 

ADDR  Returns  the  absolute  memory  address  of  a 

variable,  an  array,  or  a  structure. 

SIZE  Returns  (in  bytes)  the  storage  size  of  a  variable, 

an  array,  or  a  structure. 

ERR  Returns  the  error  code  of  the  most  recent  error. 

PEEK  Returns  the  byte  value  at  a  specified  memory 

address. 

POS  Returns  the  current  character  position  of  the 

print  buffer. 

ASC  Returns  the  numeric  value  (ASCII  code)  of  a 

string  character. 

LEN  Returns  the  length  of  a  string. 

SUBSTR  Returns  the  starting  position  of  the  specified 

substring  within  a  string,  or  returns  0  if  it 
cannot  find  the  substring. 
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Functions  performing  bit-by-bit  logical  operations  on  inte- 
ger or  byte  data  and  returning  integer  results.  Do  not  con- 
fuse these  functions  with  Boolean  type  operators. 

LAND  Calculates  the  logical  AND  of  two  values. 

LOR  Calculates  the  logical  OR  of  two  values. 

LXOR  Calculates  the  logical  EXCLUSIVE  OR  of  two 

values. 

LNOT  Calculates  the  logical  NOT  of  a  value. 

Functions  returning  a  result  of  type  string 

CHR$  Returns  the  character  having  a  specified  ASCII 

value. 

DATE$  Returns  the  system's  current  date  and  time. 

LEFT$  Returns  the  specified  number  of  characters 

beginning  at  the  leftmost  character  of  the 

specified  string. 

RIGHTS  Returns  the  specified  number  of  characters 

beginning  at  the  rightmost  character  of  the 
specified  string  and  counting  backward. 

MID$  Returns  the  specified  number  of  characters 

starting  at  the  specified  position  in  a  string. 

STR$  Converts  numeric  type  data  to  string  type. 

TRIM$  Removes  trailing  spaces  from  the  specified 

string. 


Functions  returning  Boolean  values 

TRUE  Always  returns  TRUE. 

FALSE  Always  returns  FALSE. 

EOF  Tests  for  the  end  of  a  disk  file.  Returns  TRUE 

when  the  end  of  the  file  occurs. 
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Disk  Files 


When  you  tell  OS-9  or  BASIC09  to  store  (save)  data  on  a  disk,  it 
stores  the  data  in  a  logical  block  called  a  file.  The  term  logical 
means  that,  although  the  system  might  store  portions  of  a  file's 
data  in  several  different  disk  locations,  it  keeps  track  of  every 
location  and  treats  the  scattered  data  as  though  it  occupied  a 
single  block.  It  does  this  automatically  and  you  never  need  to 
worry  about  how  the  data  is  stored.  Pile  data  can  be  binary 
data,  textual  data  (ASCII  characters),  or  any  other  useful 
information. 

Because  OS-9  handles  all  hardware  input/output  devices  (disk 
drives,  printers,  terminals,  and  so  on)  in  the  same  manner,  you 
can  send  data  to  any  of  these  devices  in  the  same  way.  This 
means  you  can  send  the  same  information  to  several  devices  by 
changing  the  path  the  data  follows.  For  example,  you  can  test  a 
procedure  that  communicates  with  a  terminal  by  transferring 
data  to  and  from  a  disk  drive. 

BASIC09  normally  works  with  two  types  of  files — sequential 
files  and  random  access  files.  The  following  chart  shows  file- 
access  options,  their  purposes,  and  the  keywords  with  which  to 
use  them: 


Types  of  Access  for  Files 


Access 
Type 

Function 

Use  with 

DIR 

Opens  a  directory  file  for  reading. 
Use  only  with  READ. 

OPEN 

EXEC 

Specifies  that  the  file  to  open  or 
create  is  in  the  execution  directory, 
rather  than  the  data  directory. 

OPEN 
CREATE 

READ 

Lets  you  read  data  from  the 
specified  file  or  device. 

OPEN 
CREATE 

WRITE 

Lets  you  write  data  to  the  specified 
file  or  device. 

OPEN 

CREATE 

UPDATE 

Lets  you  read  data  from  and  write 
data  to  the  specified  file  or  device. 

OPEN 

CREATE 
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Sequential  Files 

Sequential  files  send  or  receive  (WRITE  or  READ)  textual  data 
in  order,  the  second  item  following  the  first,  and  so  on.  %u  can 
access  sequential  data  only  in  the  same  order  as  you  originally 
stored  it.  To  read  from  or  write  to  a  particular  section  of  a  file, 
you  must  first  read  through  all  the  preceding  data  in  the  file, 
starting  from  the  beginning. 

BASIC09  stores  sequential  file  data  as  ASCII  characters.  Each 
block  of  data  is  separated  by  a  delimiter  consisting  of  a  carriage- 
return  character  (ASCII  Character  13).  Because  BASIC09  uses 
this  delimiter  to  determine  the  end  of  a  record,  sequential  files 
can  contain  records  of  varying  length. 

Use  the  WRITE  and  READ  commands  to  store  and  retrieve  data 
in  sequential  files.  A  WRITE  command  causes  BASIC09  to 
transfer  specified  data  to  a  specified  file,  ending  the  data  with  a 
carriage  return.  A  READ  command  causes  BASIC09  to  load 
from  the  specified  file  the  next  block  of  data,  stopping  when  it 
reaches  a  carriage  return. 


Sequential  File  Creation,  Storage,  and  Retrieval 

BASIC09  uses  the  CREATE  command  to  establish  both  sequen- 
tial and  random  access  files.  A  CREATE  statement  contains: 

•  The  keyword  CREATE. 

•  A  path  number  variable  in  which  BASIC09  stores  the 
number  of  the  path  it  opens  to  the  new  file. 

•  A  comma,  followed  by  the  name  of  the  file  to  create. 

•  An  optional  colon,  followed  by  the  access  mode.  If  you  do 
not  specify  an  access  mode,  BASIC09  automatically 
opens  the  created  file  in  the  UPDATE  mode. 
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The  following  procedure  shows  how  to  create  a  file  and  write 
data  into  it: 

PROCEDURE  makefile 

DDIM  PATH: BYTE  (•  establishes  a  variable 

QREM  for  the  path  number  to  the  file 


□CREATE  *PflTH,"te5t":WRiTE 
□WRITE  #PATH,"This  is  a  test" 
□WRITE  #PATH,"of  sequential  files." 
□CLOSE  #PATH 
□SHELL  "LIST  TEST" 
ZEND 


♦  creates  the  file  TEST 

<  writes  data  to  the  file 

<  writes  another  line  of  data 
>  cioses  the  path  to  the  file 
»  displays  the  file  contents 


The  first  line  of  the  procedure  dimensions  a  variable  (Path)  to 
hold  the  number  of  the  path  that  CREATE  opens.  This  variable 
should  be  of  byte  or  integer  type. 

When  you  establish  a  new  file  with  CREATE,  you  automatically 
open  a  path  to  the  file.  You  do  not  need  to  use  the  OPEN 
command. 

The  preceding  procedure  writes  two  lines  into  a  file  named  Test. 
It  then  closes  the  path  and  uses  the  OS-9  LIST  command  to  dis- 
play the  contents  of  the  newly  created  file.  You  see  that  the  data 
is  successfully  stored  on  disk. 

The  next  procedure  shows  how  to  reopen  an  existing  file  for 
sequential  access,  read  the  contents  of  the  file,  and  append  data 
to  the  end  of  the  file. 

The  only  way  to  move  the  file  pointer  to  the  end  of  a  sequential 
file  is  to  read  all  the  data  already  in  the  file.  Once  the  pointer  is 
at  the  end  of  the  file,  you  can  add  data. 

PROCEDURE  append 

□DIM  PflTH:BYT£  {♦  dimension  variable  to  hold  the  number  of  the 

□REM  path  to  the  opened  file, 

□OPEN  #PATH,"test":LiPDATE         («  open  file  for  reading  and  writing. 

□READ  'PATH, line*  («  read  the  first  element  of  the  file. 

□READ  *PATH,line$  (>  read  the  next  (the  last)  element. 

□WRITE  *PATH,"Tnis  Is  a  test"  («  write  one  new  line  to  the  file. 

□hRITE  'PATH, "of  appending  to  a  sequential  file."  («  write  another. 

□CLOSE  'PATH  (♦  close  the  path, 

□SHELL  "LIST  TEST"  t*  display  the  file  with  the  new  lines. 

□END 
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Because  the  Test  file  already  exists,  this  procedure  uses  OPEN 
to  establish  a  path  to  the  file.  It  uses  the  UPDATE  mode  of  file 
access  because  it  needs  to  both  read  from  and  write  to  the  file. 

The  two  READ  statements  read  the  file's  contents  and,  as  a 
result,  move  the  file  pointer  to  the  end  of  the  file.  The  WRITE 
statements  then  append  two  new  lines.  After  closing  the  path, 
the  procedure  calls  on  the  OS-9  LIST  command  to  display  the 
contents  of  the  file,  with  its  appended  lines. 

Changing  Data  in  a  Sequential  File 

You  can  also  change  data  anywhere  in  a  sequential  file.  How- 
ever, if  your  changes  are  longer  than  the  original  data,  the  oper- 
ation destroys  part  of  the  file.  To  change  data  in  a  sequential 
file,  read  the  data  preceding  what  you  want  to  change,  and  write 
the  new  data  to  the  file  in  this  manner: 

PROCEDURE   replace 

DDIM  PATH: BYTE 

DQPEN  'PATH, "test": UPDATE 

DREAD  'PATH.linel 

DREAD  'PATH, line! 

OWRiTE  'PATH, "Let's  put  new"      i*  write  over  existing  3rd  and 

DWRITE  iPATH.'Wds  into  the  Did  sequential  file."  («  4th  lines. 

DCLDSE  'PATH 

DSHELL  "LIST  TEST" 

DEND 

Notice  that  the  total  amount  of  data  in  the  two  new  lines  is 
exactly  the  same  as  in  the  two  old  lines.  You  can  replace  an 
existing  line  with  fewer  characters  by  padding  the  new  data 
with  spaces.  However,  if  you  try  to  replace  existing  lines  with 
longer  lines,  the  new  lines  write  over  and  destroy  other  data  in 
the  file. 
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INPUT  and  Sequential  Files 

Although  you  can  also  use  the  INPUT  command  with  sequential 
files,  doing  so  might  put  unwanted  data  into  them.  When  a  pro- 
cedure encounters  INPUT,  it  suspends  execution  and  sends  a 
question  mark  (?)  to  the  screen.  This  feature  makes  INPUT  both 
an  input  and  output  statement.  Therefore,  if  you  open  a  file 
using  the  UPDATE  mode,  INPUT  writes  its  prompts  to  the  file, 
destroying  data.  If  you  specify  text  to  be  displayed  with  the 
INPUT  command,  INPUT  writes  this  text  to  the  file  also. 

Random  Access  Files 

Random  access  files  store  data  in  fixed-  or  equal-length  blocks. 
Because  each  record  in  a  specific  file  is  the  same  size,  you  can 
easily  calculate  the  position  of  a  record. 

For  instance,  suppose  you  have  a  file  with  a  record  length  of  50- 
bytes  (or  characters).  To  access  Record  10,  multiply  the  record 
number  (10)  by  the  record  length  (50)  and  move  the  file  pointer 
to  the  calculated  position  (500). 

A  random  access  file  sends  and  receives  data  (using  PUT  and 
GET)  in  a  binary  form,  exactly  as  BASIC09  stores  it  internally. 
This  feature  minimizes  the  time  involved  in  converting  the  data 
to  and  from  ASCII  representation,  as  well  as  reducing  the  file 
space  required  to  store  numeric  data.  %u  position  the  random 
access  file  pointer  using  SEEK.  Compared  to  sequential  file 
access,  random  file  access  using  GET  and  PUT  is  very  fast. 

Using  random  access  commands,  you  can  store  and  retrieve  indi- 
vidual bytes,  strings  of  bytes,  individual  elements  of  arrays  or 
total  arrays  with  one  PUT  or  GET  command.  When  you  GET  a 
structure,  you  recover  the  number  of  bytes  associated  with  that 
type  of  structure. 

This  means  when  you  GET  one  element  of  byte  type  data,  you 
read  one  byte.  When  you  GET  one  element  of  real  type  data,  you 
read  five  bytes.  If  you  GET  an  array,  you  read  all  the  elements  of 
the  array.  This  potential  for  reading  entire  arrays  at  once  can 
greatly  speed  disk  access. 

As  well  as  moving  the  file  pointer  to  the  beginning  of  individual 
records,  you  can  also  move  it  to  any  position  within  a  record  and 
begin  reading  or  writing  one  or  more  bytes  from  that  point. 
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Creating  Random  Access  Files 

You  create  and  open  random  access  files  in  the  same  way  you 
create  and  open  sequential  files.  The  only  differences  are  in  the 
commands  you  use  to  store  and  retrieve  the  data  and  in  the 
manner  you  keep  track  of  where  elements,  or  records,  of  a  file 
begin  and  end. 

Before  you  can  write  data  to  a  random  access  file,  you  must 
either  CREATE  it  or  open  it  in  the  WRITE  or  UPDATE  mode. 
Once  you  have  a  path  open  to  an  existing  file,  use  PUT  to  write 
data  into  the  file.  If  you  open  the  file  in  the  READ  or  UPDATE 
mode,  you  can  then  use  the  GET  command  to  retrieve  data  from 
the  file. 

The  PUT  command  can  use  only  one  parameter,  the  name  of  the 
data  element  to  store.  The  parameter  can  be  a  string,  a  variable, 
an  array,  or  a  complex  data  structure. 

Before  storing  data,  you  must  devise  a  method  to  store  it  in 
blocks  of  equal  size.  Knowing  the  unit  size  lets  you  later  retrieve 
the  data  in  its  original  form.  The  following  procedure  shows  one 
way  to  do  this: 

PROCEDURE  put  get 

OREM  This  procedure  creates  a  file  named  Testl,  reads  18  data  lines, 
EREM  PUTs  then  into  the  file,  then  closes  the  file.  Next  it 
DREM  opens  the  file  in  the  READ  mode,  GETS  stored  lines  and  lists 
JREM  them  on  the  display  screen. 

DDIM  LENGTH: BYTE 

DDIM  NULL: STRING! 25! 

DDIM  L!NE:STRING(25) 

DDIM  PATH: BYTE 

□LENGTN=25 

DNULL'"" 

DBASE  i 

DON  ERROR  GOTO  18 

DDELETE  "testl"  (»  if  the  file  exists,  delete  it. 

1IDDN  ERROR 

CCREATE  »PATH,"testt":WRITE  <«  create  a  file  named  testl. 
L70R  T«8  TO  9 
■   CSEEK  #PATH,LENGTK«T  {«  find  beginning  of  each  file. 

EREAD  LINE*  («  read  a  line  of  data. 

EPUT  *PATH,LINE$  (.  store  the  line  In  the  file. 

CNEXT  T 
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LCLDSE  'PATH  (♦  close  the  file. 

DOPEH  #PATH,"teitr:P,EAD       (»  open  the  file  for  reading, 

DFDR  M  TO  9 

OSEEK  *PftTH,LENGTH«T  («  find  the  beginning  of  egch  file, 

HGET  #PATH,UNE  (♦  get  b  line  from  the  file. 

EPRINT  LINE  (>  display  the  line. 

DOT  T 


CCLOSE  *PATr 

1 

<•  close  the  fi 

le 

TEND 

DJATA 

"This 

15 

test 

line 

*t" 

DDATA 

"This 

is 

test 

line 

*2" 

DDATA 

"This 

is 

test 

line 

#3" 

DDATA 

"This 

15 

test 

line 

#4" 

CDATfl 

"This 

is 

test 

line 

#B" 

DATA 

"This 

is 

test 

line 

»6" 

DDATA 

"This 

is 

test 

line 

#7" 

DDATA 

"This 

is 

test 

line 

*8" 

DDATA 

"This 

is 

test 

line 

<9" 

DDATA 

"This 

is 

test 

line 

#10" 

This  procedure  creates  a  file  named  Testl.  The  variable  named 
Length  stores  the  length  of  each  line  in  the  file  (25  characters). 
The  string  variable  Null,  is  a  string  of  25  space  characters.  The 
variable  Line  contains  the  data  to  store  in  each  element  (record) 
in  the  file.  The  variable  Path  stores  the  path  number  of  the  file. 

Next,  the  procedure  contains  an  ON  ERROR  routine  that  deletes 
the  file  Testl,  if  it  already  exists.  Without  this  routine,  the  pro- 
cedure produces  an  error  if  you  execute  it  more  than  once. 

Next,  the  routine  uses  CREATE  to  open  the  file  Testl.  The  line 
SEEK  #PATH,  LENOTH*T  sets  the  file  pointer  to  the  proper  loca- 
tion to  store  the  next  line.  Because  Length  is  established  as  25, 
the  file  lines  are  stored  at  0,  25,  50,  75,  and  so  on. 

After  the  routine  initializes  storage  space,  it  begins  to  store 
data  by  reading  the  procedure  data  lines  one  at  a  time,  seeking 
the  proper  file  location,  and  putting  the  data  into  the  file.  After 
storing  all  10  lines,  it  closes  the  file. 
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The  last  part  of  the  routine  opens  the  new  file,  uses  the  same 
SEEK  routine  to  position  the  file  pointer,  and  reads  the  lines 
back,  one  at  a  time,  to  confirm  that  the  store  routine  is 
successful. 

The  next  short  routine  shows  how  you  can  use  a  procedure  to 
read  any  line  you  select  in  the  file,  without  reading  any  preced- 
ing lines: 

PROCEDURE  randomreod 
DDIM  LENfiTHiBYTE 
DDIM  LINEiSTRIN0!2S] 
DDIM  SEEKLINErHYTE 
DDIM  PATH:BYTE 
DLENGTH-25 

□OPEN  *PATH,"test1":REftD  0  open  the  file  for  reading. 

□INPUT  "Line  number  to  display. ..",SEEKLINE  (»  type  a  line  to  get. 
GEKITIF  SEEKLINE>1!  OR  SEEKUNE<1  THEN  («  test  if  record  is  valid. 
GENDEXIT  (.  e,jt  loop  if  not. 

□SEEK  #PflTH,C5EEKLlHE-1 J-LENGTH  (♦  find  the  requested  record. 

D6ET  *PATH,LINE  {.  fMd  the  record. 

□PRINT  LINE  (.  display  the  record, 

DPR  I NT 
QENDLDOP 

DPR  I  NT  "That's  all  "  (•  end  session. 

□CLOSE  'PATH  (•  close  path, 

□END 

The  procedure  asks  for  the  record  number  of  the  line  to  display. 
When  you  type  the  number  (1-10)  and  press  [Inter"),  SEEK  moves 
the  file  pointer  to  the  beginning  of  the  record  you  want,  GET 
reads  it  into  the  variable  Line,  and  PRINT  displays  it.  The  cal- 
culation CSEEKLIN£-1>*LENGTH  determines  the  beginning  of 
the  line  you  want.  If  you  type  a  number  outside  the  range  of 
lines  contained  in  the  file  (1-10),  the  procedure  drops  down  to 
Line  100  and  ends. 

By  changing  this  procedure  slightly,  you  can  replace  any  line  in 
the  procedure  with  another  line.  The  altered  procedure  below 
demonstrates  this: 
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PROCEDURE  random—replace 
DD!M  LENGTH: BVTE 
HDIM  LINE:STRIHG12S] 
CD1M  SEEKLINE:BYTE 
DDiM  PfiTH:BYTE 
DLEN6TH=2S 

CDPEN  *PATH,"testt":UPDATEC»  open  the  file. 

DLODP 

DINPUT  "Line  number  to  display.. .".SEEKLIHE  (»  type  record  to  find. 

HEXITIF  SEEKL1NE>1I  OR  SEEKLINE<1  THEN  (»  lest  if  valid  number. 

CENDEHIT  (»  exit  loop  if  not 

DSEEK  #PflTH ,< SEEKL1NE- 1 J "LENGTH  (♦  find  the  requested  record. 

CfcET  'PATH, LINE  (»  get  the  data. 

DPRINT  LINE  <♦  print  the  record. 

DPR  INT 

DINPUT  "Type  new  line...  ".LINE  (»  type  a  new  line. 

GSEEK  #PATH,(SEEKLIHE-1)»LENGTH  (•  find  beginning  of  the  record. 

DPUT  *PATH,LINE  («  store  the  new  line, 

CENDLOOP  (♦  do  it  all  again. 

QPRINT  "That's  all  "       C«  terminate  procedure. 

OCLOSE  'PATH  (»  close  path. 

HEND 

This  time,  the  file  is  opened  in  the  UPDATE  mode  to  allow  both 
reading  and  writing.  You  type  the  line  you  want  to  display.  A 
prompt  then  asks  you  to  type  a  new  line.  The  procedure 
exchanges  the  new  line  for  the  original  line,  and  stores  it  back  in 
the  file. 

Using  Arrays  With  Random  Access  Files 

BASIC09's  random  access  filing  system  is  even  more  impressive 
when  used  with  data  structures,  such  as  arrays.  Instead  of  using 
a  loop  to  store  the  10  lines  of  the  Random—replace  procedure, 
you  could  store  them  all  at  once,  into  one  record,  using  an  array. 
The  following  procedure  illustrates  this: 
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PROCEDURE  arraywrite 
DDIM  LENGTH: BYTE 
QDIK  LINE:STRINO(25! 
DDIM  RECDRDC1 8 > : STRINOI 25] 

DDIM  PATH: BYTE 
DLENGTH=25 

DON  ERROR  SOTO  11 

DDELETE  "testl"  (»  delete  Testl  if  It  exists. 

ION  ERROR 

DCREftTE  #PfiTH,"test1":WRITE  (»  create  Testl. 

DBASE  i 

DFOR  T«l  TO  9 

DREAD  RECQRD(T)  (•  Read  data  lines  into  RECORD  array. 

DNEXT  T 

DSEEK  'PATH, 8  (»  set  pointer  to  beginning  of  file. 

DPOT  #PATH,RECQRD  («  store  the  entire  array  into  file. 

DCLOSE  *PATH  (.  close  path  to  file, 

DOPEN  #PflTH,"test1":READ  U  open  the  file  to  read. 

DFOR  T-l  TO  9 

DSEEK  'PATH, LENGTH »T  (*  find  each  element. 

DGET  *PATH,LINE  («  read  an  element. 

DPR1MT  LINE  (»  print  the  element. 

DNEXT  T 

DCLOSE  #PATH 

DEND 

DDATA  "This  is  test  line  *1" 

DDATfl  "This  is  test  line  i2" 

DDATA  "This  is  test  line  #3" 

DDATA  "This  Is  test  line  #4" 

DDATA  "This  is  test  line  #5" 

DDATA  "This  is  test  line  *G" 

CDATA  "This  is  test  line  *7" 

CDATA  "This  is  test  line  '8" 

CDATA  "This  is  test  line  #9" 

DDATA  "This  is  test  line  #11" 
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This  procedure  reads  the  10  lines  into  an  array  named  Records. 
Then  it  places  the  entire  array  in  the  Testl  file,  using  one  PUT 
statement.  To  show  that  the  structure  of  the  file  is  still  the 
same,  the  original  FOR/NEXT  loop  reads  the  lines,  one  at  a 
time,  and  displays  them. 

Notice  that,  because  you  need  to  write  only  one  element,  you  can 
set  the  file  pointer  to  0  (SEEK  #  path,  a).  You  can  rewind  a  file 
pointer  (set  it  to  0)  at  any  time  in  this  manner. 

You  could  save  additional  programming  space  by  also  reading  the 
10  lines  back  into  memory  as  an  array.  The  following  procedure 
uses  a  new  array,  Readlines,  to  call  the  file  back  into  memory, 
and  displays  the  lines. 

PROCEDURE  arreyresd 

OBfiSE  I 

DIM  RE ADL I NE5C1 1 > : STR IMGC 25 ] 

CD1M  PATH: BYTE 

CDPEH  #PATH,"tMt1":READ  («  open  file. 

CGET  WITH, READL  IKES  <»  read  file  into  array, 

CCLDSE  *PATH 

CFOR  T-B  TO  9 

EPRINT  REftDLINES(T)  («  print  each  element  of  the  array. 

DNEXT  T 

HEND 


Using  Complex  Data  Structures 

In  the  previous  section,  you  stored  and  retrieved  elements  of  an 
array  that  were  all  the  same  size,  25  characters.  Often  you  need 
to  store  elements  of  varying  sizes,  such  as  when  you  create  a 
data  base  program  with  several  fields  in  one  record. 

The  following  examples  create  a  simple  inventory  system  that 
requires  a  random  access  file  having  100  records.  Each  record 
includes  the  name  of  the  item  (a  25-byte  string),  the  item's  list 
price  and  cost  (both  real  numbers),  and  the  quantity  on  hand  (an 
integer). 
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First,  you  use  the  TYPE  command  to  define  a  new  data  type 
that  describes  such  a  record.  For  example: 

TYPE    INV_ITEM-NAME:STRING[2S];LIST,C0ST:REAL; 
QTY: INTEGER 

Although  this  statement  describes  a  new  record  type  called 
Inv_item,  it  does  not  assign  variable  storage  for  the  record.  The 
next  step  is  to  create  two  data  structures:  an  array  of  100  rec- 
ords of  type  Inv_item  named  Inv_array  and  a  working  record 
named 
Work_rec.  The  following  lines  do  this: 

DIM    INV_ARRAY<100):  INV—ITEM 
DIM   WORK—REC:  INV_ITEM 

To  determine  the  number  of  bytes  assigned  for  each  type,  you 
can  use  BASIC09's  SIZE  command.  SIZE  returns  the  number  of 
bytes  assigned  to  any  variable,  array,  or  complex  data  structure. 
For  example,  the  command  line  SIZE(W0RKI_REC>  returns  the 
number  37.  The  command  SI2EC  INV_ARRAY)  returns  the  num- 
ber 370  0. 

You  can  use  SIZE  with  SEEK  to  position  a  file  pointer  to  a  spe- 
cific record's  address. 

The  following  procedure  creates  a  file  called  Inventory  and 
immediately  initializes  it  with  zeroes  and  nulls  strings.  Five 
INPUT  lines  then  ask  you  for  a  record  number  and  the  data  to 
store  in  each  field  of  the  record.  You  can  fill  any  record  you 
choose,  from  1  through  100. 

When  one  record  is  complete,  the  procedure  uses  PUT  to  store 
the  record.  Then,  it  asks  you  for  a  new  record  number.  If  you 
wish  to  quit,  enter  a  number  either  larger  than  100  or  smaller 
than  1. 

PROCEDURE  inventory 

CREM  Create  a  data  type  consisting  of  a  25-character  name  field, 

DREW  a  real  list  price  field,  a  real  cost  field,  and  an  integer 

QREM  quantity  field. 

□TYPE  INV — ITEM=NAME: STRING! 251;  LIST, COST: REAL;  QTY: INTEGER 

DDIH  INV_ARRA»{188):  INV—ITEM  <»  dimension  an  array  using  new  type, 
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GDIM  WORK REC:INV ITEM 

DREM  {*  dimension  a  worling  variable  of  the  new  type. 

DDIM  PSTH:BVTE 

DON  ERROR  GOTO  1 i 
DDELETE  "inventory" 
1«D0N  ERROR 

DCREATE  t PATH, "inventory"       (»  create  a  file  named  Inventory. 
DWORK — REC.HflME-"  («  set  all  data  elements  to  null  or  8. 

DMORK REC.L1ST=8 

OMORK REC.CDST=0 

DWORK REC.QTY-fl 

DFOR  N=l  TO  IK 
DPUT  *PATH,WORK_REC 
DNEXT  N 

DLOOP 

."J1NPUT  "Record  number?  ",RNUM  (»  enter  number  of  record  to  write, 

DIE  RNUttl  OR  RNUM>18B  THEN      (•  check  if  number  is  valid. 

DPR  I  NT 

OPRINT  "End  of  Session"  («  if  not,  end  session. 

DPR  INT 

DCLOSE  'PATH 

DEND 

DEND IF 

DINPUT  "Item  name?  ".WORK RECLAME    («  type  data  for  record. 

DNPUT  "List  price?  ",  WORK—RE  C.LI  ST 

DINPUT  "Cost  price?  ",WORK REC.COST 

DINPUT  "Quantity?  ",W0RtC REC.QTY 

CSEEK  *P«TH,(RNUM-1)»S1ZE(W0RK_REC)  (♦  find  record. 

DPUT  #PATH,WDRK REC  (•  write  record  to  file. 

DENDLOQP 

Notice  that  the  INPUT  statements  reference  each  field  sepa- 
rately, but  the  PUT  statement  references  the  record  as  a  whole. 

The  next  procedure  lets  you  read  any  record  in  your  Inventory 
file,  and  displays  that  record.  If  you  ask  for  a  record  you  have  not 
yet  filled  with  meaningful  data,  the  display  consists  of  a  null 
string  and  zeroes. 

PROCEDURE  readinv 

HTYPE  I NV — ITEM-NftME:  STRING  [251;  LI  ST, COST:  REAL;  OH:  INTEGER 

DDIM  WORK REC:!NV ITEM 


8-13 


BASIC09  Reference 


DDIM  PATH: BYTE 

HOPEN  'PATH, "INVENTORY"; RE AD 

GLDQP 

QINPUT  "Record  number  to  display?  ",RNUM 

DIP  RNUM<1  OR  RNUMXIJ  THEN 

DPR I NT  "End  of  Session" 

DPR  INT 

DOLOSE  IPATH 

LEND 

CENDIF 

DSEEK  #PflTH,CHHUH-1>»SIZECW0HK REC) 

DOET  #PftTH,UORK REC 

DPR  I  NT  "#","11 em", "List  Price",  "Cost  Price","Ouantlty" 

QPRiNT  " 

DPRINT  RHUH, WDRK — REC . NAME .WORK REC . LIST, WORK REC . COST ,WDRK REC . QT¥ 

DPR I NT 

DENDLOOP 

DEND 


This  procedure  accesses  the  file  one  record  at  a  time.  It  is  not 
necessary  to  do  so.  You  can  read  the  entire  file  into  memory  at 
once  by  dimensioning  an  inventory  array  and  getting  the  whole 
file  into  it: 

DTlfPE  [NLITEM=NANE! STRING! 253;  L1ST,CDST:REAL;  Q.TY:  INTEGER 
QDIM  INV_ARRAY<1ii):IN.V_IT£M 
DSEEK  »PATH,S       ( 'rewind  the  fileO 
DGET  *PATH,INV_ARRAY 

The  examples  in  this  section  are  simple,  yet  they  illustrate  the 
combined  power  of  BASIC09  complex  data  structures  and  the 
random  access  file  statements.  They  show  that  a  single  GET  or 
PUT  statement  can  move  any  amount  of  data,  organized  in  any 
way  you  want.  Other  advantages  are  of  using  complex  data  struc- 
tures are: 

•  The  procedures  are  self-documenting.  You  can  see  easily 
what  a  procedure  does  because  its  structures  can  have 
descriptive  names. 

•  Execution  is  extremely  fast. 

•  Procedures  are  simple  and  usually  require  fewer  state- 
ments to  perform  I/O  functions  than  other  BASICs. 
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The  procedures  are  versatile.  By  creating  appropriate 
data  structures,  you  can  read  or  write  almost  any  kind 
of  data  from  any  file,  including  files  created  by  other  pro- 
grams or  languages. 
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BASIC09  has  three  levels  of  graphics  capabilities.  The  first  and 
third  levels  can  include  both  graphics  designs  and  text.  The  sec- 
ond level  can  display  only  graphics  designs. 

ASCII  Codes 

For  low-resolution  text  screens  and  high-resolution  text  and 
graphic  screens,  BASIC09  uses  ASCII  (American  Standard  Code 
for  Information  Interchange)  codes  to  represent  the  common 
alphanumeric  characters.  ASCII  is  the  same  code  that  most 
small  computers  use. 

A  table  of  the  standard  codes  follows: 

Table  9.1 

BASIC09  ASCII  Codes  0-127 

Low-  and  High-Resolution  Screens 

Character  Decimal  Code      Hexadecimal  Code 


[  BREAK  | 

03 

03 

s 

8 

08 

Q 

9 

09 

LD 

10 

OA 

[ CLEAR  J 

12 
13 

oc 

OD 

| ENTER  1 

Space 

32 

20 

1 

33 

21 

« 

34 

22 

# 

35 

23 

$ 

36 

24 

% 

37 

25 

& 

38 

26 

9 

39 

27 

( 

40 

28 

) 

41 

29 

* 

42 

2A 

+ 

43 

2B 

* 

44 

2C 

45 

2D 

46 

2E 

/ 

47 

2F 

0 

48 

30 
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Character 

Decimal  Code 

Hexadecimal  Code 

1 

49 

31 

2 

50 

32 

/"N 

3 

51 

33 

4 

52 

34 

5 

53 

35 

6 

54 

36 

7 

55 

37 

8 

56 

38 

9 

57 

39 

58 

3A 

J 

59 

3B 

< 

60 

3C 

= 

61 

3D 

> 

62 

3E 

? 

63 

3F 

(c<> 

64 

40 

A 

65 

41 

B 

66 

42 

C 

67 

43 

D 

68 

44 

/"~v 

E 

69 

45 

F 

70 

46 

G 

71 

47 

H 

72 

48 

I 

73 

49 

J 

74 

4A 

K 

75 

4B 

L 

76 

4C 

M 

77 

4D 

N 

78 

4E 

0 

79 

4F 

P 

80 

50 

Q 

81 

51 

R 

82 

52 

S 

83 

53 

T 

84 

54 

U 

85 

55 

V 

86 

56 

^~S 

w 

87 

57 

X 

88 

58 

Y 

89 

59 

Z 

90 

5A 

[  (1  SHIFT  ]|  +  |) 

91 

5B 
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Decimal  Code      Hexadecimal  Code 

5C 

5D 

5E 

5F 

60 

61 

62 

63 

64 

65 

66 

67 

68 

69 

6A 

6B 

6C 

6D 

6E 

6F 

70 

71 

72 

73 

74 

75 

76 

77 

78 

79 

7A 

7B 

7C 

7D 

7E 

7F 

"Vbu  can  generate  the  characters  in  this  chart  by  pressing  the 
appropriate  key,  or  you  can  generate  them  from  BASIC09  using 
the  CHR$  function. 


Character               E 

•ecims 

\   (|  SHIFT  ||  CLEAR  |) 

92 

]  (|  SHIFT  ||  -H) 

93 

♦ 

94 

-*■  (|  SHIFT  ||  ♦  I) 

95 

A 

96 

a 

97 

b 

98 

c 

99 

d 

100 

e 

101 

f 

102 

S 

103 

h 

104 

i 

105 

J 

106 

k 

107 

1 

108 

m 

109 

n 

110 

0 

111 

P 

112 

q 

113 

r 

114 

8 

115 

t 

116 

U 

117 

V 

118 

w 

119 

X 

120 

y 

121 

z 

122 

{ 

123 

124 

} 

125 

I 

126 

127 
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Low-Resolution  Graphic  Characters 

In  addition  to  alphanumeric  characters,  low-resolution  graphics 
also  offers  graphic  characters.  Generate  these  characters  by 
pressing  [alt j  at  the  same  time  you  press  a  keyboard  character, 
The  graphics  character  codes  are  in  the  range  128-255, 

Pressing  [alt I  while  pressing  another  key,  causes  OS-9  to  add 
128  to  the  ASCII  value  of  the  second  key.  (Pbr  the  technically 
minded,  OS-9  sets  the  high  bit  of  the  character  code.)  Therefore, 
if  you  press  [alt  |  {a},  you  produce  graphics  character  193.  "Vbu  can 
also  generate  graphics  characters  from  BASIC09  using  the 
CHR$  function,  and  you  can  PRINT  them  in  the  same  manner 
as  other  characters. 

Low-level  graphics  characters  follow  a  pattern  that  repeats  every 
16  characters.  Table  9.2  shows  the  first  set  of  graphic  characters, 
128-143.  Subsequent  characters  produce  the  same  series  of  con- 
figurations but  display  in  different  colors,  as  shown  in  Table  9.3. 

Table  9.2 
Low-Resolution  Graphic  Character  Set 

Character  Code  Character  Code  Character  Code  Character  Code 


128 


132 


136 


140 


129 


133 


137 


141 


130 


134 


138 


142 


131 


135 


139 


143 
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Table  9.3 

Low-Resolution  Graphics  Color  Set 

ASCII  Code 

Graphics  Block  Color 

128  -  143 

Black  and  Green 

144  -  159 

Black  and  "Yellow 

160  -  175 

Black  and  Blue 

176  -  191 

Black  and  Red 

192  -  207 

Black  and  Buff 

208  ■  223 

Black  and  Light  Blue 

224  -  239 

Black  and  Cyan 

240  -  254 

Black  and  Orange 

255 

Green 

Within  each  color  set,  you  can  easily  calculate  the  number  for  a 
particular  character.  For  instance,  suppose  you  want  to  print  a 
character  that  has  orange  upper  left  and  lower  right  corners.  Pic- 
ture the  character  divided  into  four  sections,  numbered  as 
follows: 


lb  calculate  a  character  that  has  orange  at  Sections  8  and  1,  add 
the  section  values  to  the  first  value  in  the  orange  group,  240, 
like  this: 

240  +  8  +  1  =  249 

Character  249  is  what  you  want. 

The  following  diagram  shows  how  you  might  block  out  a  large 
letter  O  on  the  screen.  The  shaded  portions  of  the  characters  are 
colored.  The  unshaded  portions  are  black.  In  this  case  we  want 
the  colored  portions  to  be  green  (the  same  color  as  the  screen). 
You  can  do  this  using  the  color  set  128  - 143. 
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Because  Section  1  in  the  upper  left  character  is  to  be  colored, 
add  1  to  the  initial  character  value  of  128.  The  first  character 
value  is  129.  Moving  right,  Sections  2  and  1  are  colored  in  the 
second  character.  Add  3  to  128  to  get  a  second  character  value  of 
131.  Calculate  all  15  characters  in  this  manner. 

You  could  create  a  letter  O  in  a  BASIC09  procedure  by  printing 
each  of  the  five  rows  of  three  characters.  You  could  use  DATA 
lines  to  store  the  ASCII  codes  for  each  character,  then  use  loops 
to  read  and  display  the  characters  they  represent. 

Although  low-level  graphics  is  very  rough,  it  can  be  useful,  and 
it  lets  you  mix  graphics  with  text. 

The  following  procedure  not  only  creates  the  letter  O,  it  adds  the 
letter  S  and  the  number  9  to  display  the  name  of  your  operating 
system. 
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PROCEDURE  oa9prog 

DDIM  DAT: INTEGER 

DPRINT  CHRIC12) 

DPR  I  NT 

DPRINT 

DPRINT 

DFQR  2-1  TD  5 

DPRINT  TABC10); 

DFOR  T=1  TO  12 

OREAD  DAT 

GPRINT  CHRStDAT); 

DNEXT   T 

jPRINT 

"NEXT   Z 

CEND 

DDATA    129,131  ,130,143,129,131  ,131  ,143,129,131  ,130, 

143 

DDATA    133,143,138,143,133,143,143,143,132,140,136, 

143 

DDATA    133,143,138,143,132,140,140,143,131 ,131 ,130, 

143 

DDATA    133,143,138,143,131 ,131 ,130,143,143,143,138, 

143 

DDATA    132,140,136,143,140,140,136,143,143,143,138, 

143 
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Special  Characters  in  High-Resolution 

High-resolution  graphics  does  not  have  graphic  characters  but  it 
does  have  other  international  and  special  characters.  These  char- 
acters are  represented  by  ASCII  codes  128  through  159  as  shown 
in  the  following  table: 

Table  9.4 
High-Resolution  Special  Characters 


Hex 

Decimal 

Hex 

Decimal 

Character 

Code 

Code 

Character 

Code 

Code 

C 

80 

128 

6 

90 

144 

u 

81 

129 

£e 

91 

145 

e 

82 

130 

m 

92 

146 

a 

83 

131 

6 

93 

147 

a 

84 

132 

d 

94 

148 

a 

85 

133 

0 

95 

149 

a 

86 

134 

u 

96 

150 

C. 

87 

135 

u 

97 

151 

e 

88 

136 

0 

98 

152 

e 

89 

137 

6 

99 

153 

e 

8A 

138 

0 

9A 

154 

i 

8B 

139 

§ 

9B 

155 

1 

8C 

140 

£ 

9C 

156 

B 

8D 

141 

+ 

9D 

157 

A 

8E 

142 

a 

9E 

158 

A 

8F 

143 

/ 

9F 

159 

Medium-Resolution  Graphics 

For  more  sophisticated  graphics  operations,  OS-9  has  built-in 
graphics  interface  modules  that  provide  a  convenient  way  to 
access  the  graphics  and  joystick  functions  of  the  Color  Computer 
3.  The  required  module  for  medium-resolution  graphics  is  named 
GFX.  It  must  be  in  your  execution  directory  or  resident  in  mem- 
ory when  called  by  BASIC09. 

You  can  either  install  GFX  in  memory  using  the  LOAD  com- 
mand, or  wait  until  BASIC09  calls  it  for  a  graphics  function. 
Once  loaded,  GFX  resides  in  memory  until  you  remove  it  using 
the  OS-9  UNLINK  command  or  the  BASIC09  KILL  command. 
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GFX  has  a  number  of  functions  that  you  pass  to  it  as  parame- 
ters with  the  RUN  statement.  For  instance,  the  following  state- 
ment clears  the  current  graphics  screen: 


RUN   GFXC'CLEAR") 


Other  tasks  need  such  parameters  as  position,  color,  and  size. 
The  following  is  a  quick  reference  to  all  of  the  GFX  functions. 
Each  is  explained  in  detail  later: 


Function      Purpose 


ALPHA        Sets  the  screen  to  the 

alphanumeric  mode. 

CIRCLE      Draws  a  circle. 


CLEAR        Clears  the  screen  to  a 
color. 

COLOR        Changes  the  foreground 

and  background  colors. 

GCOLR        Reads  a  pixel's  color. 


GLOC  Returns  a  video  display 

address. 

JOYSTK       Returns  the  joystick 
button  and  X-  and  Y- 
coordinate  status. 

LINE  Draws  a  line. 


MODE  Switches  the  screen 

between  alphanumeric 
and  graphics,  sets  the 
graphics  screen  color. 

MOVE  Positions  the  invisible 

graphics  cursor. 


Parameters 


None. 


Radius,  optional  X-  and 
Y-coordinates,  and  color. 

Optional  color  for  screen. 


Foreground  and 
background  colors. 

Names  of  variables  in 
which  to  store  optional 
X-  and  Y-coordinates. 

None. 


Names  of  variables  in 
which  to  return  the 
values. 

Ending  X-  and  Y- 
coordinates,  optional 
beginning  coordinates, 
optional  color. 

Format,  Color. 


X-  and  Y-coordinates. 
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Function      Purpose 


Parameters 


POINT  Moves  graphics  cursor 

and  sets  a  point. 

QUIT  Returns  screen  to 

alphanumeric  mode. 
Deallocates  graphics 
memory. 


X-  and  Y-coordinates 
and  optional  pixel  color. 

None. 


Formats  and  Colors 

In  medium-resolution  graphics,  you  have  a  choice  of  two  formats. 
Format  0  provides  256  horizontal  points  by  192  vertical  points.  In 
this  format,  you  can  have  only  two  colors  on  the  screen  at  a  time. 

Format  1  provides  a  128  by  192  point  screen  and  a  maximum  of 
four  colors  on  the  screen  at  a  time.  OS-9  medium-resolution 
graphics  treats  the  screen  as  if  it  were  a  grid,  with  coordinate 
0,0  at  the  lower  left  corner  as  shown  in  the  following  illustration. 
All  points  on  the  grid  are  positive. 


Y-coordinate,0  - 


I    I    I    I    I    I 

0,  X-coordinate 


I     I 


BASIC09  defines  colors  with  numbers  or  color  codes.  Many  GFX 
functions  allow  or  require  color  codes  as  parameters.  BASIC 09 
also  divides  the  color  codes  into  color  sets.  Specifying  a  color  code 
outside  the  current  color  set  automatically  initializes  the  new 
set. 
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Color 

Set 


Color 
Code 

Format  0 

Back- 
ground 

Fore- 
ground 

00 

01 
02 

03 

Black 
Black 

Black 
Green 

04 
05 
06 

07 

Black 
Black 

Black 
Buff 

Color 
Code 

Format  1 

Back- 
ground 

Fore- 
ground 

00 
01 
02 

03 

Green 
Green 
Green 
Green 

Green 
Yellow 

Blue 
Red 

04 
05 
06 

07 

Buff 
Buff 
Buff 
Buff 

Buff 
Cyan 
Magenta 
Orange 

08 
09 
10 
11  . 

Black 
Black 
Black 
Black 

Black 
Dk  Green 
Md  Green 
Lt  Green 

12 

13 
14 
15 

Black 
Black 
Black 
Black 

Black 
Green 
Red 
Buff 

Table  9.5 

Use  the  preceding  charts  to  chose  colors  for  those  functions  that 
let  you  specify  foreground  or  background  colors.  For  instance,  to 
initialize  a  Format  1  graphics  screen  with  a  green  background 
and  a  red  foreground,  you  type: 

run    gfx("mode",1 ,3) 

The  following  reference  section  describes  all  the  medium-resolu- 
tion graphics  functions,  and  provides  examples  and  sample  pro- 
grams. To  understand  the  organization  of  the  commands 
reference,  see  "The  Syntax  Line"  in  Chapter  11. 
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The  Draw  Pointer 

Medium-resolution  graphics  uses  a  draw  pointer,  or  invisible 
graphics  cursor,  to  determine  what  area  of  the  screen  is  affected 
by  graphics  operations.  When  you  establish  a  graphics  screen, 
the  draw  pointer  is  located  at  coordinates  0,0.  Some  graphic 
functions  automatically  change  the  pointer  location  on  the 
screen.  For  instance,  the  LINE  function  moves  the  draw  pointer 
from  the  beginning  coordinates  to  the  end  coordinates. 

Because  some  functions  begin  at  the  draw  pointer,  you  need  to 
keep  track  of  its  location  and  make  certain  it  is  placed  properly. 
Use  the  MOVE  function  to  set  the  draw  pointer  to  new  locations. 
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r^ 


ALiift±  A    Select  alphanumeric  screen 


Syntax:      RUN  GFXC'ALPHA") 

Function:  Switches  from  the  graphics  screen  to  the  alphanu- 
meric (text)  screen.  The  current  graphics  screen  remains 

intact. 

Parameters:  None 
Examples: 

RUN   GFXCALPHA") 

Sample  Program: 

This  procedure  lets  you  choose  to  draw  a  circle  or  rectangle  of 
the  size  you  select.  Once  you  choose  the  shape  and  size,  it  uses 
the  MODE  function  to  select  a  graphics  screen.  When  the  shape 
is  complete,  you  press  I  enter  I  to  return  to  a  text  screen.  The  pro- 
cedure uses  the  ALPHA  function  to  return  to  the  original  menu. 

PROCEDURE  alpha 

DDIM  XCDR,YC0R,SIDE1 ,SIDE2 .RADIUS ,T , X , Y ,Z: INTEGER 

DDIM  RESPQNSE:STRING[1 ] 

10  REPEAT 

DSHELL  "DISPLAY  0C" 

[PRINT  "Do  you  want  to  draw" 

QPRINT  "1)  A  rectangle" 

3PRINT  "2)  A  circle" 

GPRINT  "    -Press  1  or  2. . ."; 

DGET  #0, RESPONSE 

DPR  I  NT 

DIF  RESP0NSE="1"  THEN 

DINPUT  "Length  of  Side  1,..",SIDE1 

DINPUT  "Length  of  Side  2...",SIDE2 

DRUN  GFX( "MODE", 0,0) 

DRUN  GFXC'CLEAR") 

DXCQR-10 

DYCOR-10 

DRUN  GFX("LINE",XC0R,YC0R,XC0R  +  SIDE1  ,YCDR,1 ) 
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IRUN   GFX("LINEM,XC0R+SIDE1  ,YC0R,XC0R+SIDE1 ,ycor  + 

SIDE2.1 > 

DRUN  GFX("LINE",XCaR*SIDE1  ,  YCOR+S  IDE2  ,  XCOR  ,  YCOR  + 

SIDE2.1J 

DRUN  GFX ("LINE", XCOR, YCOR  +  S  I DE2 , XCOR  ,  YCOR  ,  1 ) 

DINPUT  RESPONSE 

QELSE 

GIF  RESP0NSE*"2"  THEN 

DINPUT  "What  radius?. . .".RADIUS 

"RUN  GFXCMMODE",0 ,1 ) 

CRUN  GFX("CLEAR"> 

LRUN  GFX ("CIRCLE" ,128, 90, RAD  I  US) 

DINPUT  RESPONSE 

DENDIF 

DENDIF 

DUNTIL  RESPONSE<>"1"  AND  RESP0NSE<>"2" 

GRUN  GFX("ALPHA"> 

3GOTO  1 0 

CEND 
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KsLl\\sLihi    Draw  a  circle 


Syntax:       RUN  GFX("CIRCLE"[,xcar,jcor],radius  [>color]) 

Function:  Draws  a  circle  of  a  given  radius.  If  you  do  not  spec- 
ify a  color,  BASIC09  uses  trie  current  foreground  color.  If  you 
do  not  specify  X-  and  Y-coordinates,  CIRCLE  uses  the  current 
graphics  cursor  position  as  the  circle's  center. 


Parameters: 

radius 
color 

xcorsycor 
Examples: 


The  radius  of  the  circle  you  want  to  draw. 

The  code  of  the  color  you  want  the  circle  to  be. 

See  the  chart  earlier  in  this  section  for  color 
information. 

The  X-  and  Y-coordinates  for  the  center  of  the 
circle.  Specifying  coordinates  outside  the  X- 
coordinate  range  of  0-255  or  outside  the  Y- 
coordinate  range  of  0-191  causes  an  error. 


RUN  GFX<"CIRCLE",100> 

RUN  GFX(,,CIRCLE",100,35 

RUN  GFXC"CIRCLE,,,125,100,100> 

RUN  GFX("CIRCLE",125, 100,100,2) 

Sample  Program: 

This  procedure  uses  CIRCLE  to  draw  and  erase  a  circle.  The 
location  of  the  circle  changes  before  each  draw/erase  operation, 
causing  the  circle  to  move.  When  it  hits  the  edge  of  the  screen, 
it  reverses  its  direction  at  a  random  angle  and  bounces. 

PROCEDURE  circles 

DDIM  RADIUS, XC0R,YC0R; INTEGER 

DDIM  XTEMP.YTEMP: INTEGER 
DDIM  PATH1 ,PATH2: INTEGER 
DDIM  FLAG: INTEGER 
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3FLA0-1 

CXCOR-S 

CYCOR-S 

DPATH1=RNDC15)+2 

DPATH2>RND<18)+2 

OXTEMP-249 

DYTEMP-185 

DRUN   GFX(*'MODE",0,1) 

CRUN   GFXC'CLEAR") 

DFDR   T*1    TO    200 

QWHILE    XCDR<2E0    AND   XCDR>4   AND   YC0R<186   AND   YC0R>4 

DO 

ORUN  GFXC'C I RCLE" , XTEMP , YTEHP ,3 , 2) 

DRUN  GFX<"CIRCLE",XCOR,YC0R,3,1 > 

jXTEMP-XCOR 

CYTEMP-YCDR 

CXCOR-XCOR+PATH1 

CYC0R-YCOR+PATH2 

CENDWHILE 

DPATH1»=RND(15>*2 

DPATH2-RND<1 0J  +  2 

GIF  XC0R>249  THEN 

DXCOR-249 

DENDIF 

DIF    XCDR<5    THEN 

DXCOR-B 

DENDIF 

DIF   YC0R>185   THEN 

CYCOR-185 

CENDIF 

DIF    YCOR<S   THEN 

DYC0R=5 

DENDIF 

DFLAG-FLAGt-1 

DIF   FLAG<0   THEN 

DPATH1«PATH1*-1 

jPATH2=PATH2»-1 

jENDIF 

CNEXT   T 

CEND 
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CLEAR    Clear  the 


screen 


Syntax:      RUN  GFX("CLEAR"[,eo/or]) 

Function:  Clears  the  current  graphics  screen.  If  you  do  not 

specify  a  color,  CLEAR  sets  the  entire  screen  to  the  current 
background  color.  CLEAR  also  sets  the  graphics  cursor  at 
coordinates  0,0,  the  lower  left  corner  of  the  screen. 

Parameters: 

color  A  code  indicating  the  color  to  set  the  screen. 

Examples: 

RUN   GFXC'CLEAR") 
RUN   GFXC'CLEAR", 14) 
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OOLiOrv    Change  the  foreground  color 


Syntax:      RUN  GFXC'COLOR",  color) 


Function:  Changes  the  foreground  color  (and  possibly  the  color 
set).  COLOR  does  not  change  the  graphics  format  or  the  cur- 
sor position. 

Parameters: 

color  A  code  indicating  the  color  you  want  for  the 

foreground.  See  the  chart  earlier  in  this  chap- 
ter for  color  information. 

Examples: 

RUN   GFX<"C0L0R",1fl) 

Sample  Program: 

This  procedure  connects  a  series  of  differently  colored  circles  to 
produce  a  necklace  effect. 

PROCEDURE  necklace 

QDIM  COLOR, T,U, J, R,FL AG ,XCOR,YCOR: INTEGER 

DRUN  GFXCMODE"  ,1  ,03 

GRUN  GFXCCLEAR") 

GC0L0R=1 

3XC0R»1 

IYCOR-1 

IR-2 

LTOR  T  =  1  TO  S 

LTOR  J  =  1  TO  40 

CXCOR-XCOR+1 

CYCDR-YCDR+.8 

DIF  FLAG<0  THEN 

DR=R-1 

DELSE 

DR=R+1 

DENDIF 

DCDL0R=C0L0R+1 

DIF  C0L0R>3  THEN  C0LOR=1 
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DENDIF 

DRUN   OFXC,,CIRCLEM,XCDR,YC0R,R,COLOR> 

ONEXT   J 

l]FLAG-FLAG»-1 

UNEXT   T 

DFOR   U=1    TO    10000 

3NEXT   U 

CEND 
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«wL     Find  the  graphics  screen  location 


Syntax:      RUN  GFX("GLOC",storage) 

Function:  Determines  the  location  of  the  graphics  screen  in 
memory  and  returns  the  address  in  the  specified  variable. 
When  you  know  the  graphic  screen  address,  you  can  use 
PEEK  and  POKE  to  perform  special  functions  not  available  in 
the  GFX  module,  such  as  filling  a  portion  of  the  screen  with  a 
color  or  saving  a  graphics  screen  to  disk. 

OS-9  Level  Two  maps  display  screens  into  a  program's 
address  space  before  PEEK  and  POKE  can  operate  on  a  dis- 
play screen.  This  means  that  you  must  have  at  least  eight 
kilobytes  of  free  memory  in  the  user's  address  space.  Program 

and  data  memory  requirements  must  not  exceed  56  kilobytes. 

Parameters: 

storage  An  integer  or  byte  type  variable  in  which 

GLOC  stores  the  memory  address  of  the 
graphics  screen. 

Examples: 

RUN   GFXC'GLOC", location) 

Sample  Program: 

This  procedure  uses  the  GLOC  function  to  locate  the  current 
graphics  screen,  then  uses  POKE  to  paint  a  series  of  boxes  on 
the  screen. 

PROCEDURE  boxin 

CDIM  LOCATION, PLACE, COLOR, BEGIN, QUIT, X, TERMINATE, 

LINE.T.J: INTEGER 

jRUN  GFX<"MDDE«M  ,0) 

□RUN  GFXC'CLEAR") 

DRUN  GFX<"GLOC", LOCATION) 

DLDCATION-LOCATION+100  \  PLACE-LOCATION 

DBEGIN-1 

DQUIT-80 
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DCDL0R=255 

DTERMINATE=10 

DLINE-32 

DFOR  X  =  1  TO  4 

DFOR  T=1  TO  QUIT 

DFOR  J-BEOIN  TO  TERMINATE 

DPOKE  PLACE+J.COLOR 

DNEXT  J 

DPLACE=PLACE+L1NE 

CNEXT  T 

DLDCATIDN-LOCATION+1G0 

DBEGIN-BEGIN+1 

DPLACE=LOCATION 

DQUIT-OUIT-10 

DTERMINATE=TERMINATE-1 

DCOLOR-CDLaR-85 

DNEXT  X 

DINPUT  z* 

GEND 
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JOYSTK    Get  joystick  status 


Syntax:      RUN  GFX(" JOYSTK", stick, Gre,xcor,ycor) 

Function:  Determines  the  status  of  the  specified  joystick  fire 
button  and  the  X,Y  position  of  the  specified  joystick  handle. 
Use  this  function  only  with  a  standard  joystick  or  mouse,  not 
with  the  high-resolution  mouse  adapter. 


Parameters: 

stick 

fire 


xcor,ycor 


Examples: 


The  joystick  (0  or  1)  for  which  you  want  to 

determine  the  status.  0  indicates  the  right  joy- 
stick, 1  indicates  the  left  joystick. 

A  variable  in  which  JOYSTK  returns  the  sta- 
tus of  the  specified  fire  button.  Fire  can  be 
byte,  integer,  or  Boolean  type.  A  value  other 
than  0  or  TRUE  indicates  the  button  is 
pressed. 

Byte  or  integer  type  variables  in  which 
JOYSTK  stores  the  X-  and  Y-coordinates  of 
the  joystick  handle  position.  The  coordinate 
range  is  0-63. 


RUN   GFXCJOYSTK-.B, shoot  ,x,y) 
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Sample  Program: 

This  procedure  uses  the  JOYSTK  function  to  draw  on  the  screen 
with  the  right  joystick. 

PROCEDURE    joydraw 

HDIM   STICK,FIRE,XCOR,YCDR,XTEMP,YTEMP: INTEGER 

jRUN    GFX< "MODE", 0,1 ) 

:run  gfx<"clear") 
cjoy=0  \xcor=0  \ycdr=0 

OREPEAT 

DXTEMP-XCDR 

DYTEMP-YCOR 

DRUN  GFX(,«JDYSTK,\0,FIRE,XCOR,YCDR) 

GXC0R=XC0R*4 

CYC0R=YC0R*4 

CRUN  GFXC"LINEM,XTE!nP,YTEMP,XCOR,YC0R) 

DUNTIL  FIREoB 

DEND 
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LINE    Draw  a  line 


Syntax:      RUN  GFX("LINE"[,xcorl,yeorl],xcor2,yeor2 

[,co!or]) 

Function:  Draws  a  line  in  the  current  or  specified  foreground 
color  in  one  of  the  following  ways: 

•  From  the  current  draw  position  to  the  specified  X,Y- 
coordinates. 

•  From  the  specified  beginning  X-  and  Y-coordinates  to  the 
specified  ending  X,Y-coordinates. 

Parameters: 

xcorl,ycorl        Are  LINE's  beginning  X-  and  Y-coordinates. 

xcor2,ycor2        Are  LINE's  ending  X-  and  Y-coordinates. 

color  A  code  indicating  the  color  you  want  the  line 

to  be.  See  the  chart  earlier  in  this  section  for 
color  information. 

Examples: 

RUN   GFX<"LINE",192,128> 
RUN   GFX<"IINE", 0,0, 192,128) 
RUN   GFXCLINE", 0,0, 192, 128,2) 
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Sample  Program: 

This  procedure  draws  a  sine  wave  of  vertical  lines  across  the 
screen. 

PROCEDURE  waves 

DDIM  A,B,C,D,X,Y,Z:INTeGER 

DCALC-0  \  A  =  100 

DRUM  GFXt"mode,,,0,1  ) 

DRUN  GFXC-CLEAR") 

DRUN  GFX<"C0LDR",2) 

DFOR  X-0  TO  255  STEP  1 

GCALC-CALC+.05 

HY=A-SINCCALC>*1S 

UZ-Y+25 

DRUN  GFX(,,LINE",X,Y,X,Z) 

F.NEXT  X 

LEND 
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MODE     Switch  to  graphics 


screen 


Syntax:      RUN  GFX("MODE",/orma*,eolor) 

Function:  Switches  the  screen  from  alphanumeric  (text)  to 
graphics,  selecting  the  screen  format  and  color  code.  You  must 
run  MODE  before  you  can  use  any  other  graphics  function. 
When  you  do,  BASIC09  allocates  a  six-kilobyte  block  of  mem- 
ory for  graphics.  If  your  system  does  not  have  this  amount  of 
memory  available,  OS-9  returns  an  error  message. 

Parameters: 

format  Either  0  (a  two-color  256  by  192  pixel  screen) 

or  1  (a  four-color,  128  by  192  pixel  screen). 

color  A  code  indicating  the  color  to  set  the  screen. 

See  the  chart  earlier  in  this  chapter  for  infor- 
mation on  color  sets. 

Examples: 

RUN    GFXCMaDE",!  ,2) 
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MOVE     Movegraphi 


ics  cursor 


Syntax:      RUN  GFX("MOVE",xcor,ycor) 

Function:  Moves  the  invisible  graphics  cursor  to  the  specified 
location  on  the  screen.  MOVE  does  not  change  the  display  in 
any  way. 

Parameters: 

xcor,ycor  The  coordinates  for  the  cursor. 

Examples: 

RUN   GFXC'MOVE" ,192,128) 

Sample  Program: 

This  procedure  draws  and  pops  bubbles  on  the  screen  using  the 
CIRCLE  function.  It  uses  MOVE  to  select  the  position  for  the 
circles. 

PROCEDURE  bubbles 

idim  xcdr,ycdr,t,r,array(3,1 00): integer 
:run  gfxcmdde-.i  ,0) 

irun  gfxcclear") 

IFOR   T-1    TD    20 

IARRAY<1 ,T)=RND<2SS) 

lARRAY(2,T)-RND<192) 

L"ARRAY<3,T)-RND<50) 

GRUN   GFX<"M0VE",ARRAY(1 , T) , ARRAY(2 , T) ) 

DRUN   GFXC"CIRCLE",ARRAY(3,T),3) 

DNEXT    T 

DFCIR    T-1     TO    20 

DRUN   GFXC,,M0VEM,ARRAY(1  ,  T)  ,  ARRAY(2  ,  T>> 

DRUN   GFX ("CIRCLE" , ARRAY(3,T) ,0) 

QSHELL  "DISPLAY  07" 

DNEXT  T 

GEND 
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Jr  OIW  I     Set  point  to  specified  color 


Syntax:      RUN  GFX("POINT",xcor>ycort,color]) 

Function:  Displays  a  dot  at  the  specified  coordinates.  If  you 
specify  a  color,  POINT  sets  the  pixel  at  the  new  coordinates  to 
that  color.  Otherwise,  POINT  sets  the  pixel  at  the  new  coordi- 
nates to  the  foreground  color. 

Parameters: 

xcorycor  The  X-  and  Y-coordinates  for  a  pixel. 

color  The  code  of  the  color  you  want  the  pixel  to  be. 

See  the  chart  earlier  in  this  section  for  color 
information. 

Examples: 

RUN   GFX<"P0INT",192,128> 
RUN   GFX<"PQINT",192,128,2) 

Sample  Program: 

This  procedure  uses  POINT  to  draw  filled  boxes  on  the  screen. 

PROCEDURE  boxup 

CDIM  XCOR, YCOR, BEG IN.CDLDR, QUIT, TERM  I  NATE, LINE: 

INTEGER 

DDIM  T,X,Y: INTEGER 

QXCOR-50  \YCOR*30  \C0L0R»1 

DBEGIN-1  \START-1  \QUIT-20  \TERMI NATE-E0 

URUN  GFXC'MQDE'-.I  ,0) 

DRUN  GFXC"CLEAR"J 

IFOR  T=1  TO  4 

CFOR  X'BEGIN  TO  QUIT 

CFOR  Y-START  TO  TERMINATE 

DRUN  GFX("POINT",XC0R+Y,YCOR,C0LOR> 

DNEXT  Y 

DYC0R-YC0R+1 

QNEXT   X 

DSTART-START+10 
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CTERMINATE=TERMINATE~1 0 
□C0LOR=COLOR+1 
□NEXT  T 
HINPUT  Z$ 

QEND 
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\$\J  1 1     Deallocate  graphics  screen 


Syntax:      RUN  GFXC'QUIT") 

Function:  Switches  the  screen  to  the  alphanumeric  (text)  mode 
and  deallocates  graphics  memory. 

Parameters:  None 

Examples: 

RUN   GFXC'QUIT") 
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High-Resolution  Graphics 

BASIC09's  high-resolution  graphics  greatly  expand  the  capabili- 
ties of  the  Color  Computer  3.  You  can  have  greater  screen  resolu- 
tion (up  to  640  by  192  pixels),  as  many  as  64  colors,  and  the 
ability  to  mix  graphics  and  text  on  one  screen.  In  addition,  you 
can  use  different  text  fonts,  or  styles. 

The  high-resolution  module,  GFX2,  has  many  more  functions 
than  its  medium  resolution  counterpart.  GFX2  gives  you  the 
ability  to: 

•  Select  from  64  colors,  OS-9  provides  a  palette  with  16 
default  colors.  You  can  change  any  of  these  default  colors  to 
any  of  the  64  colors  available  on  the  Color  Computer  3. 

•  Set  border  colors. 

•  Set  color  patterns. 

•  Create  different  types  of  graphics  screen  cursors. 

•  Use  logic  functions. 

•  Turn  an  automatic  scaling  function  off  or  on. 

•  Draw  outline  or  filled  boxes, 

•  Draw  ellipses  and  arcs. 

•  Fill  specified  areas  with  specified  colors. 

•  GET  and  PUT  sections  of  the  graphics  screen. 

•  Select  character  fonts,  which  include  boldfaced,  transparent, 
and  proportionally  spaced  characters. 

•  Move  the  cursor.  Erase  portions  of  a  line  or  of  the  screen. 

•  Select  reverse  or  normal  video. 

•  Underline  text. 

Also,  high-resolution  graphics  operate  through  the  OS-9  Win- 
dowing System,  This  means  that  you  can  run  several  procedures 
in  different  windows.  You  can  establish  windows  to  display  text, 
or  to  display  graphics,  or  both.  You  can  easily  display  any 
window. 


9-31 


BASIC09  Reference 


Establishing  a  Hardware  Window 

Jbr  your  convenience,  OS-9  has  a  number  of  predefined  or  hard- 
ware window  formats.  Hardware  windows  are  text  windows,  and 
you  cannot  use  them  for  graphic  applications.  Because  hardware 
windows  are  predefined,  you  can  easily  establish  them  with  the 
INIZ  command.  R>r  instance,  to  establish  Window  7,  type: 


inlz   w7  [  enter  1 


However,  you  cannot  see  the  window  until  you  send  a  message  to 
it.  Type: 


echo    Hello   Window   7    >    /w7  I  ENTER  I 


Now,  to  see  the  window  and  your  message  press  |  clear  |.  To 
return  to  the  original  screen,  press  I  clear  1  again. 

To  OS-9,  a  window  is  a  device  and  you  can  send  data  to  it.  To 
view  the  Errmsg  file  in  the  SYS  directory  of  your  system 
diskette,  list  it  to  Window  7  by  typing: 


list    sys/errmsg    >    /w7  [  ENTER  | 

Press  ["clear]  to  move  to  Window  7  and  see  the  listing.  Press 
I  shift  ||  clear]  to  return  to  the  previous  screen. 

You  can  also  fork  a  shell  (an  execution  environment)  to  a  win- 
dow. To  cause  a  shell  to  operate  in  Window  7,  type: 


shell    i  =  /w7s  I  ENTER  I 


The  i  -  function  of  SHELL  tells  OS-9  that  the  window  is  im- 
mortal. It  does  not  die  after  completing  a  task.  To  operate  OS-9 
from  the  window,  press  I  clear  |. 

Besides  Window  7,  you  have  six  other  predefined  windows.  The 
following  chart  shows  all  the  hardware  windows  and  their 
parameters: 
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Starting 

Coordinates 

Window 

Screen  Size 

X-Coord, 

Window  Size 

Number 

Chars/line 

Y-Coord 

Cols 

Rows 

1 

40 

0,0 

27 

11 

2 

40 

28,0 

12 

11 

3 

40 

0,12 

40 

12 

4 

80 

0,0 

60 

11 

5 

80 

60,0 

19 

11 

6 

80 

0,13 

80 

12 

7 

80 

0,0 

80 

24 

Defining  Windows 

As  well  as  hardware  windows,  OS-9  also  lets  you  establish  win- 
dows to  your  own  specifications.  You  can  set  definable  windows 
for  either  text  or  graphics,  or  both.  You  can  locate  them  any- 
where on  a  screen,  and  you  can  make  them  any  size. 

You  initialize  definable  windows  in  the  same  manner  you  initial- 
ize hardware  windows,  using  INEZ.  If  you  want  to  have  text  on 
the  window,  you  must  merge  SYS/Stdfonts  (found  on  your  system 
diskette)  with  the  window.  You  can  also  establish  a  shell  in  a 
definable  window,  from  which  you  can  use  OS-9  or  BASIC09. 

To  establish  definable  windows  you  must  supply  OS-9  with  infor- 
mation about  the  type  of  window  you  want  (its  graphic  format), 
its  size,  and  its  location  on  the  screen.  The  easiest  way  to  do  this 
is  with  the  OS-9  WCREATE  command. 
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WCREATE  requires  a  window  format  code  in  the  form 
-  5=  format  cods  to  tell  OS-9  what  type  of  a  window  you  want. 
The  following  chart  shows  the  possible  window  formats  you  can 
choose: 


Table  9.6 


Format      Screen  Size 

Resolution. 

No.  of 

Memory 

Screen 

Code       Cols  x  Rows 

Width/Height 

Colors 

Required 

Type 

01                 40  x  24 



16t 

1600 

Text 

02                 80  x  24 



16t 

4000 

Text 

05               80  x  24 

640  x  192 

2 

16000 

Graphics 

06                 40  x  24 

320  x  192 

4 

16000 

Graphics 

07               80  x  24 

640  x  192 

4 

32000 

Graphics 

08               40  x  24 

320  x  192 

16 

32000 

Graphics 

00*     Specifies  the  current  screen. 

FF      Current  display  i 

screen.  Use  when  putting  several  windows 

on  the  same 

physical  screen. 

t  You  have  to  reconfigure  the  palette  to  get  16  colors  rather  than  the  default  of 
eight  colors.  The  following  section  provides  information  on  the  palette. 

Format  Codes  01  and  02  select  text  screens,  and  Format  Codes  5- 
8  select  graphics  screens.  The  Screen  Size  column  shows  the 
maximum  number  of  text  columns  and  rows  available  for  each 
screen.  The  Resolution  column  shows  the  maximum  pixels 
(graphic  units)  available  for  each  of  the  graphic  screens.  The 
Memory  column  shows  how  much  memory  OS-9  must  set  aside 
for  each  screen  format.  Memory  requirements  depend  on  the  res- 
olution and  number  of  colors  selected  for  a  window. 


The  Palette 

BASIC09  has  64  colors  you  can  select  for  screen  displays.  The 
colors  are  available  through  a  palette.  The  Color  Computer's  pal- 
ette can  hold  16  colors  at  once. 
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The  following  chart  shows  the  default  colors  for  the  palette  in 
Screen  Format  7: 

Table  9.7 


Register 

Color 

Register 

Color 

00 

Black 

08 

Black 

01 

Red 

09 

Green 

02 

Green 

10 

Black 

03 

^fellow 

11 

Buff 

04 

Blue 

12 

Black 

05 

Magenta 

13 

Green 

06 

Cyan 

14 

Black 

07 

White 

15 

Orange 

Instead  of  the  default  colors,  you  can  select  any  of  the  64  colors 
(0-63)  for  any  of  the  palette  registers,  %u  do  this  using  the  PAL- 
ETTE command  described  later  in  this  chapter.  The  BORDER 
and  COLOR  commands  also  affect  the  colors  available  in  the  pal- 
ette by  changing  the  color  in  the  background  and  foreground 
registers,  Registers  02  and  03,  respectively. 

Note:  The  information  in  the  next  section  assumes  you  have 
a  Color  Computer  3  with  512  kilobytes  of  memory.  If  your 
computer  has  128  kilobytes  of  memory,  skip  to  the  section 
"High-Level  Graphics  With  128K." 

Establishing  a  Graphics  Window 

To  create  any  window,  you  should  first  initialize  it  with  the  INIZ 
command.  Type: 


iniz   w1     ENTER! 


So  that  you  can  later  type  in  the  new  window,  merge  the 
Stdfonts  file  with  it.  Type: 


merge    5ys/5tdf  ont  5  >/w1  |  EMTER  I 

Using  the  information  in  the  preceding  tables,  use  WCREATE  to 
establish  a  graphics  window.  The  following  command  line  creates 
a  graphics  window  in  Window  1  that  has  320  x  192  resolution 
and  that  fills  the  entire  screen.  The  new  window  has  16  colors 
available  and  provides  40  column  by  24  line  text: 
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wcreate  /w1  -s«8  00  00  40  24  03  02  02  I  ENTER  ] 


La*  The  screen  border  color 


_>  The  screen  background 
color 

->  The  screen  foreground 
color 


->  The  screen  length  in 
rows 


_>  The  screen  width  in 
columns 

_>  The  Y-Coordinate  for  the 
beginning  of  the  screen 

_>  The  X-coordinate  for  the 
beginning  of  the  screen 

_>  The  screen  type 

_3»  The  window  name 

^  The  command  name 


Starting  a  Shell  in  a  Window 

At  this  point,  the  new  window  exists,  and  you  can  send  data  to 
it.  However,  if  you  want  to  operate  from  the  window,  you  must 
install  a  shell  in  it.  Type: 


shell     l  =  /w1  *  I  ENTER  I 


Press  I  clear  |  to  move  to  the  new  window.  To  load  BASIC09,  type: 


ba5ic09   #10K  I  ENTER  | 


Select  either  more  or  less  memory,  according  to  your  needs. 
Using  BASIC09  in  a  graphics  window,  you  can  write  procedures 
to  create  high-resolution  graphics,  and  you  can  display  the 
graphics  on  the  same  screen. 
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Using  High-Level  Graphics  With  128K 

If  your  computer  is  equipped  with  only  128  kilobytes  of  memory, 
you  cannot  use  more  than  one  window  with  BASIC09.  Also,  to 
use  even  one  window,  you  must  follow  certain  steps  to  provide 
enough  memory  for  BASIC09  operations. 

Refer  to  Table  9.6.  %u  must  select  a  window  mode  that  does  not 
use  more  than  16000  byte  of  memory — either  window  Format  5 
or  Format  6. 

To  provide  enough  memory  to  use  BASIC09,  you  must  fork  a 
shell  to  the  window  you  create,  then  kill  the  shell  in  TERM. 
Doing  this  means  that  you  can  no  longer  operate  from  your 
TERM  screen.  However,  you  can  run  OS-9  and  BASIC09  from 
the  window. 

The  following  steps  show  you  how  to  create  a  Format  6  graphics 
screen  in  Window  1,  write  a  BASIC09  high-resolution  graphics 
procedure,  and  execute  it  using  minimum  memory. 

1.    Boot  OS-9.  Then,  create  a  graphics  window  by  typing: 


iniz    w1  |  ENTER | 

wcreate    /w1     ~s-06    00    00    40    24    06    01     01  !  ENTER ) 

2. 

merge    ays/stdf  ont  5>/w1    |  ENTER  |     pfC?  /-/*■/ 
shell     i-/w14  [ENTERJ                                  .  fl    ■y  a    ,  v  *„ 

«■                           ""%?- 

The  system  stops,  and  you  can  no. longer  type  or  issue  com- 
mands. Press  |  clear  |  to  move  to  the  new  window.  Then,  load 
BASIC09  by  typing: 

baslC09  |  ENTER  | 

3. 

Enter  the  edit  mode,  and  type  the  following  procedure: 

PROCEDURE    squeeze 

DDIM    XC0R,YC0R,X,Y : INTEGER;    RESPONSE : STR I NGC 1 ] 

DRUN   GFX2C"CUR0FF"> 

DXCDR-320    \    YCOR-95    \    X=300    \    FLAG-1 

DPRINT   CHRIC12) 

□LOOP 

IFOR    Y-1    TO    100    STEP   2 

jX-X-3 

IGOSUB    1 0 

ZIF   FLAG<1    THEN 

DRUN   GFX2<"COLOR",0) 
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□ELSE 

□RUN   GFX2C"C010R",3) 

QENDIF 

□RUN   0FX2("ELLIPSE",XC0R,YC0R,X,Y) 

□FLAG-FLAG*-1 

DNEXT    Y 

ORUN   GFX2("CDL0R",1) 

□FDR    Y-99   TO    1    STEP    -2 

□GDSUB   10 

□X'X+3 

□RUN   GFX2<"ELLIPSE,,,XCOR,YCOR,X,Y) 

□NEXT    Y 

□RUN   GFX2<"COLOR",0) 

□ENDLdDP 

10DRUN    INKEYCRESPONSE) 

□IF    RESPONSE-""   THEN 

□RETURN 

□ENDIF 

10DPRINT    CHR*<12) 

□RUN   GFX2C"COLOR",0> 

□RUN   GFX2C"CURON,,> 

□END 

4.  When  you  have  entered  the  procedure  exactly  as  shown,  exit 
the  edit  mode,  and  from  the  BASIC09  command  mode,  save 
Squeeze  by  typing: 


save    squeeze  (ENTER] 
5,    Compile  Squeeze  by  typing: 


pack    squeeze  I  ENTER  | 

Squeeze  is  now  an  executable  module  saved  in  your  current 
execution  directory.  The  following  steps  assume  your  execu- 
tion directory  is  /DO/CMDS. 

6.    Exit  BASIC09  by  typing: 


bye  I  ENTER  ( 

7.    Merge  Squeeze,  RUNB,  ENKEY,  and  GFX2  into  one  module. 
To  do  this,  type: 

merge    /d0/cmds/squeeze    /dfl/cmds/runb    /d0/cmd5/ 
inkey   gfx2    >    /d0/cmda/yawT)  (INTER  | 
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8.  MERGE  does  not  set  the  new  file  Yawn  as  an  executable  file. 
Before  you  execute  it,  you  must  make  the  file  executable  by 
typing: 


attr    /d0/yawn   e   pe  |  ENTER  | 
9.    To  execute  Yawn,  type: 


yown  |  ENTER  | 

10,  To  terminate  the  procedure,  press  the  space  bar, 

The  merging  procedure  in  Step  ?  saves  a  considerable  amount  of 
memory.  Every  module  you  load  uses  one  or  more  8-kilobyte 
blocks  of  storage  space.  For  instance,  INKEY  is  only  94  bytes  in 
length.  However,  if  you  load  it  as  a  separate  module,  it  requires 
8192  bytes.  RUNB  is  12185  bytes  in  length.  This  means  that  it 
requires  two  8-kilobyte  blocks,  or  16384  bytes  of  memory.  GFX2 
is  2190  bytes  in  length,  and  Squeeze  is  605  bytes  in  length. 
Loaded  individually,  they  also  require  two  memory  blocks. 

If  you  load  all  four  modules  independently,  they  use  40960  bytes. 
However,  by  combining  them  into  one  file,  they  load  into  two 
memory  blocks,  or  16384  bytes. 

Using  the  information  in  this  section,  you  can  write  and  execute 
numerous  BASIC09  procedures  with  only  128  kilobytes  of  mem- 
ory. However,  if  your  computer  has  512  kilobytes  of  memory,  you 
can  bypass  many  of  these  steps.  Also,  the  additional  memory 
enables  you  to  have  several  windows  open  at  one  time.  For 
instance,  you  can  create  one  window  in  which  to  write  BASIC09 
procedures,  another  window  in  which  to  execute  your  procedures, 
and  a  third  window  from  which  you  can  use  OS-9  commands. 

Note:  The  remainder  of  this  chapter  assumes  you  have  512 
kilobytes  of  memory.  If  you  don't,  you  can  still  run  many  of 
the  sample  procedures  by  implementing  the  steps  in  this 
section. 

Creating  Windows  from  BASIC09 

Using  GFX2  routines,  BASIC09  provides  the  means  to  create 
and  manage  windows.  The  steps  for  creating  windows  from 
BASIC09  are  as  follows: 

1.  DIM  a  variable  to  hold  the  path  number  to  the  window  you 
want  to  create. 
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2.  OPEN  a  path  to  the  window. 

3.  SELECT  the  new  window  as  the  display  window. 

4.  Send  commands,  data,  or  text  to  the  window  through  the  open 
path. 

5.  CLOSE  the  open  path. 

6.  Use  SELECT  to  return  to  your  original  window. 

If  you  do  not  want  to  return  immediately  to  the  screen  or  win- 
dow of  origin,  you  can  skip  Steps  5  and  6. 

The  following  sample  procedure  shows  how  to  open  Window  2  as 
a  320  x  192  graphics  window,  draw  a  circle,  then  return  to  the 
original  screen  when  you  press  a  key. 

PROCEDURE   make_win 

DIM  PATH: INTEGER 

DIM  RESP0NSE:STRINGE1 ] 

DPEN    #PATH,"/W2" :WRITE 

RUN   GFX2    (PATH, "DWSET", 08, 00, 00, 40, 24, 03, 02,02) 

RUN   GFX2    (PATH, "SELECT") 

RUN   GFX2    (PATH, "CIRCLE", 200, 90, 80) 

GET    #1  .RESPONSE 

CLOSE    #PATH 

RUN    GFX2    ("SELECT") 

END 

This  procedure  establishes  a  Format  8  window,  beginning  at 
Coordinates  0,0  and  covering  the  total  screen.  The  foreground 
color  is  green,  the  background  color  is  black,  and  the  border  color 
is  black. 

Because  this  procedure  does  not  INIZ  the  window  it  opens,  the 
window  automatically  disappears  when  the  procedure  closes  its 
path.  To  create  a  window  that  stays  in  the  system,  even  after 
you  close  the  path  to  it,  use  INIZ  before  the  OPEN  statement, 
Hke  this: 

SHELL   "INIZ    /W2" 

After  you  create  and  define  the  window,  view  it  by  pressing 
I  clear  j.  To  get  back  to  the  screen  you  are  working  on,  press  I  shift  | 
I  clear  [.  If  you  intend  to  use  a  window  more  than  once  in  a  proce- 
dure, you  do  not  need  to  close  its  path  until  the  procedure  no 
longer  needs  it. 
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Creating  Overlay  Windows 

When  you  establish  a  window,  you  are  initializing  an  OS-9 
device.  However,  an  overlay  window  is  only  a  new  screen  for  an 
existing  window.  An  overlay  screen  can  be  the  same  size  as  its 
window,  or  it  can  be  smaller.  OS-9  automatically  transfers  to  the 
overlay  window  any  current  procedures  operating  in  the  device 
window. 

The  process  for  creating  overlay  windows  lets  you  select  whether 
you  want  to  save  the  contents  of  the  screen  covered  by  the  new 
window.  If  you  choose  to  save  the  contents,  the  previous  screen  is 
redisplayed  when  you  end  the  overlay. 

The  folbwing  procedure  provides  an  example  of  using  overlay 
windows.  It  creates  six  overlays,  each  smaller  than  the  preceding 
window.  The  procedure  then  waits  for  you  to  press  a  key.  When 
you  do,  it  removes  the  overlay  windows. 

PROCEDURE  overwindows 

HDIM  X.Y.X1 ,Y1 , T, J, B.L, PL ACE: INTEGER 

CDIM  RESPONSEsSTRINGM ] 

CX  =  0  \Y=0 

□X1=80  \Y1=24 

□PLACE-33 

DFQR  T-1  TO  6 

DIP  T=2  OR  T=6  THEN 

□B  =  3 

HELSE  B-2 

DENDIF 

[IRUN  GFX2C"0WSET'\1  ,X,Y,X1  ,Y1  ,b,tj 

CX-X+G  \Y=Y*2 

DX1-X1-12  \Y1-Y1-4 

□FOR  J-1  TO  5 

□PRINT  TAB(PLACE);  "Overlay  Screen  " ;  T 

DNEXT  J 

DPLACE=PLACE-6 

DNEXT   T 

IPRINT  "Overlay  Screen  6" 

lPRI NT  "Press  A  Key. . ."; 

□GET  #1 .RESPONSE 

□FOR  T=1  TO  6 

DRUN  GFX2C"0WEND") 

JNEXT  T 

"END 
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The  Graphics  Cursor  and  the 
Draw  Pointer 

High-resolution  graphics  provide  a  text  cursor,  a  graphics  cursor, 
and  a  draw  pointer.  The  text  cursor  and  the  graphics  cursor  can 
be  either  visible  or  invisible.  The  draw  pointer  is  always 
invisible. 

Text  functions  always  begin  at  the  current  location  of  the  text 
cursor.  Whenever  you  print  on  the  screen,  the  cursor  automati- 
cally moves  to  the  end  of  the  text  or  to  the  beginning  of  the  next 
line,  depending  on  whether  or  not  you  use  a  semicolon  after  the 
print  statement.  You  can  reset  the  text  cursor  to  any  place  on 
the  screen  with  the  CURXY  function  of  GFX2. 

Many  BASIC09  graphics  functions  also  begin  operating  at  a 
location  pointed  to  by  the  draw  pointer.  When  you  begin  graph- 
ics, the  draw  pointer  is  located  at  coordinates  0,0.  BASIC09  then 
updates  the  pointer  as  you  execute  certain  graphics  functions. 
For  instance,  the  LINE  function  of  GFX2  draws  from  the  draw 
pointer  position  to  the  specified  end  coordinates.  The  draw 
pointer  is  left  pointing  to  the  end  coordinates. 

Because  some  functions  begin  at  the  draw  pointer,  you  need  to 
keep  track  of  its  location  and  make  certain  it  is  placed  properly. 
Use  the  SETDPTR  function  to  move  the  draw  pointer  to  new 
locations. 

The  graphics  cursor  is  for  use  with  joystick  or  mouse  operations. 
It  provides  a  pointer  for  graphics  applications.  The  system 
diskette  provides  patterns  that  can  be  loaded  into  the  graphics 
cursor  buffer.  You  can  select  from  a  variety  of  pointer  images. 

High-Resolution  Text 

When  you  create  a  graphics  window,  you  can  display  either  text 
characters,  graphics  characters,  or  both. 

To  display  graphics,  move  the  draw  pointer  to  the  location  where 
you  want  the  graphics  to  begin.  Then,  execute  the  graphics 
routines. 

To  display  text,  move  the  text  cursor  to  the  location  where  you 
want  the  text  to  begin.  Then,  use  normal  BASIC  commands  to 
print  text. 
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Instructions  for  the  draw  pointer  relate  to  a  640  x  192  grid, 
numbered  0-639  and  0-191.  Instructions  for  the  text  cursor 
relate  to  the  number  of  characters  per  line  and  the  number  of 
lines  on  the  current  screen  format. 


Using  Fonts 

OS-9  has  built-in  fonts  (character  sets),  "Vbu  can  also  create  your 
own  fonts  and  instruct  BASIC09  to  use  them.  If  you  create  your 
own  fonts,  you  can  design  any  symbols  or  graphics  characters 
you  want  to  use. 

To  use  fonts,  you  must  be  in  a  graphics  window.  See  "Establish- 
ing a  Graphics  Screen"  earlier  in  this  chapter.  Use  the  FONT 
function  to  tell  OS-9  what  font  you  want.  BASIC09  has  three 
fonts  installed  in  Group  200,  Buffers  1,  2,  and  3.  The  following 
procedure  uses  characters  in  Buffer  3  to  draw  a  border,  then 
prints  a  message  using  the  characters  in  Buffer  2.  It  then 
returns  to  Buffer  3  and  asks  you  to  press  a  key  to  end  the 
procedure. 

PROCEDURE  borders 

DDIM  T,B,V,J,K: INTEGER 

□DIM  RESPDNSE:STRINGt1 ] 

□B«199 

□PRINT  CHRIC12) 

□RUN  GFX2<"FONT",200,3) 

□RUN  GFX2(,,C0LDR",1  ,2) 

□FDR  T=0  TO  79 

□PRINT  CHRtCBJ; 

□NEXT  T 

DF0R  T=1  TO  21 

3RUN  GFX2("CURXY" ,0,T) 

"PRINT  CHR$(B>;  CHR$(B); 

CRUN  GFX2«"CURXY,,,78,T) 

CPRINT  CHR$(B);  CHR$(B); 

CNEXT  T 

CRUN  GFX2<"CURXY", 0,21) 

□FOR  T-0  TO  79 

□PRINT  CHR$CB); 

□NEXT  T 

□RUN  GFX2("FONT",200,2) 

ZIRUN  GFX2C"COIOR'\0,2) 

□RUN  GFX2C"CURXY",45,9) 

3PRINT  "A  Demonstration" 
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DRUN  GFX2C"CURXY",S0,10> 

DPRINT  "Of  A" 

DRUN  OFX2C"CURXY",43,11) 

DPRINT  "Buffer  Three  Border" 

DRUN  GFX2("CURXY",51 ,12) 

DPRINT  "And" 

DRUN  GFX2C,,CURXY,,,4E,13> 

DPRINT  "Buffer  Two  Text" 

DRUN  GFX2C"F0NT",28B,1  > 

DRUN  GFX2C,,C0L0R",3,2) 

□RUN  GFX2<"CURXY",33,15> 

DPRINT  "Press  A  Key. . ."; 

DGET  #1  , RESPONSE 

QPRINT  CHR*<12) 

DEND 

High-Resolution  Quick  Reference 

High-resolution  functions  are  all  part  of  the  GFX2  module.  You 
call  them  in  a  BASIC09  procedure  with  the  following  syntax: 

RUN   GFX2CtP/»T"H]  ," FUNCTION" I  .PARAMETERl , .  .  .])) 

Path  is  an  optional  variable  name  that  tells  OS-9  the  window  in 
which  you  want  the  function  performed.  Function  is  the  high- 
resolution  task  you  want  to  perform.  Parameter  is  an  essential  or 
optional  value  that  affects  the  performance  of  the  function.  Dif- 
ferent functions  require  or  permit  different  numbers  of 
parameters. 

The  following  reference  gives  a  brief  description  of  the  high- 
resolution  graphics  functions.  This  list  is  organized  by  function. 
Following  the  quick  reference  is  a  detailed  reference  organized 
alphabetically. 


9-44 


Displaying  Text  and  Graphics  1 9 


Window  Commands 


Command 


Function 


DWSet 


OWSet 


OWEnd 

Select 

DWEnd 

CWArea 

DWProtectSw 


Establishes  a  window  and  sets  its  location 
on  the  screen,  its  size,  its  background  color, 
its  foreground  color,  and  its  border  color. 

Establishes  an  overlay  window  on  a  device 
window  that  already  exists.  The  function 
also  sets  the  overlay  window  size,  back- 
ground color,  foreground  color,  and  border 
color.  When  using  this  function,  you  can 
choose  whether  or  not  to  save  the  contents 
of  the  original  screen. 

Deallocates  the  specified  overlay  window. 

Selects  the  window  to  display. 

Deallocates  an  established  window. 

Changes  the  size  of  a  window.  You  can  only 
reduce  the  working  area  of  a  window,  not 
increase  it. 

Lets  you  unprotect  a  window  and  set  other 
device  windows  over  it.  This  might  destroy 
the  contents  of  either  or  both  windows. 
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Drawing  Commands: 


Command 


Function 


Point 

Line 

Box 

Bar 

Circle 

Ellipse 

Arc 

Fill 

Clear 


Sets  the  pixel  under  the  draw  pointer  to  the 
specified  color  or  to  the  default  color. 

Draws  a  line. 

Draws  a  rectangle  outline. 

Draws  a  filled  rectangle. 

Draws  a  circle. 

Draws  an  ellipse. 

Draws  an  arc. 

Fills  the  area  of  the  window  the  same  color 
as  the  pixel  under  the  draw  pointer. 

Clears  the  window. 
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Configuring  Commands: 


Command 

Function 

Color 

Sets  any  of  the  foreground,  background,  or 
border  colors. 

DefCol 

Sets  palette  registers  to  the  default  colors. 

Border 

Sets  the  border  palette  register. 

Palette 

Changes  colors  in  the  palette  registers. 

Pattern 

Establishes  a  buffer  from  which  BASIC09 
gets  a  pattern  for  graphics  functions. 

Logic 

Turns  on  AND,  OR,  or  XOR  logic  functions 
for  draw  functions. 

GCSet 

Establishes  a  buffer  from  which  BASIC09 
gets  the  graphics  cursor. 

ScaleSw 

Turns  scaling  on  or  off. 

SetDPtr 

Positions  the  draw  pointer, 

PutGC 

Positions  the  graphics  cursor. 

Draw 

Draws  an  image  from  directions  provided  in 

a  draw  string. 


Get/Put  Commands: 


Command 

Function 

Get 

Saves  a  specified  portion  of  a  window  to  a 
buffer. 

Put 

Places  the  image  stored  in  a  buffer  onto  a 
window. 

^~-       DefBuff 

Defines  a  buffer  for  storage. 

GPLoad 

Preloads  a  buffer  from  a  disk  file. 

KillBuff 

Deallocates  a  buffer. 
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Text/Cursor  Handling  Routines: 


Command 


Function 


CurHome 
CurXY 

ErLine 
ErEOLine 

CurOff 

CurOn 

CurRgt 

Bell 

CurLft 

CurUp 

CurDwn 


Positions  the  cursor  at  coordinates  0,0. 

Positions     the     cursor     at     specified 
coordinates. 

Erases  the  line  under  the  cursor. 

Erases  from  the  cursor  to  the  end  of  the 
line. 

Turns  the  graphics  cursor  off. 

Turns  the  graphics  cursor  on. 

Moves  the  graphics  cursor  right  one  space. 

Sounds  the  terminal  bell. 

Moves  the  graphics  cursor  left  one  space. 

Moves  the  graphics  cursor  up  one  line. 

Moves  the  graphics  cursor  down  one  line. 
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Font  Handling  Commands: 


Command 


Function 


Font  Specifies  the  buffer  from  which  BASIC09 

selects  its  font  characters. 

TCharSw  Selects  or  deselects  transparent  characters. 

BoldSw  Selects  or  deselects  bold  characters. 

PropSw  Selects  or  deselects  proportional  characters. 

ErEoWndw  Erases  from  the  graphics  cursor  to  the  end 

of  the  window. 

Clear  Erases  window  and  homes  the  cursor. 

CrRtn  Performs  a  carriage  return  by  moving  the 

cursor  down  one  line  and  to  the  extreme  left 
of  the  window. 

ReVOn  Turns  reverse  video  on. 

ReVOff  Turns  reverse  video  off. 

UndlnOn  Turns  the  underline  function  on. 

UndlnOff  Turns  the  underline  function  off. 

BlnkOn  Turns  blinking  characters  on  (only  for  hard- 

ware text  screens). 

BlnkOff  Turns  blinking  characters  off  (only  for  hard- 

ware text  screens). 

InsLin  Inserts  a  blank  line  at  the  graphics  cursor 

position. 

DelLin  Deletes  the  line  at  the  graphics  cursor 

position. 
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ARC     Draw 


an  arc 


Syntax:      RUN  GFX2([patfi,]"ARC"[,mx,jny], 
xrad,yrad,xcorl,ycorl,xcor2,  ycor2) 


Function:  Draws  an  arc  at  the  current  or  specified  draw  posi- 
tion with  the  specified  X  and  Y  radius.  If  you  specify  the 
same  radius  for  both  X  and  Y,  the  function  draws  a  circular 
arc,  otherwise  the  arc  is  elliptical.  The  X  coordinates  are  in 
the  range  0-639.  The  Y  coordinates  are  in  the  range  0-191. 

ARC  begins  drawing  from  the  point  on  the  screen  closest  to 
the  first  set  of  coordinates  (xcorl,  ycorl).  It  stops  at  the  por- 
tion of  the  screen  closest  to  the  second  set  of  coordinates 
(xcor2,  ycor2).  You  can  determine  on  which  side  of  the  line 
ARC  draws  by  selecting  which  set  of  coordinates  is  the  begin- 
ning and  which  set  is  the  end. 


Parameters: 

path 

mx,my 


xrad 

yrad 

xcorl, ycorl 
xcor2,ycor2 


The  route  to  the  window  in  which  you  want  to 
draw  an  arc. 

The  X-  and  Y-coordinates  for  the  center  of  the 
arc.  If  you  do  not  specify  mx  and  my,  BASIC09 

uses  the  current  draw  pointer  position. 

The  radius  of  the  arc's  width. 

The  radius  of  the  arc's  height. 

The  beginning  and  ending  coordinates  for  an 
imaginary  line  from  which  the  function  draws 
an  arc.  The  line  is  relative  to  the  center  of  the 
arc  (the  center  point  is  at  0,0  for  these  coordi- 
nates) and  extends  through  the  two  coordi- 
nates from  one  edge  of  the  screen  to  the  other. 


Examples: 


RUN    GFX2("ARC",50,1 00, 50,100, 50,1  SB) 
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Sample  Program: 

This  procedure  draws  a  series  of  diagonally-cut  arcs  on  a  graph- 
ics window  screen. 

PROCEDURE  arcing 

DDIM  MX,MY,XRAD,YRAD,XCOR,YC0R,XCOR2,YC0R2: INTEGER 

DDIM  T,X,Y,Z: INTEGER 

QPRINT  CHR$C12> 

DFOR  T-1  TO  90  STEP  2 

CRUN  GFX2C"ARC,,,318,95,1S0,T,0,1  ,8,1) 

DRUN  GFX2<"ARC",324,9S,1S0,T,1 ,0,1 ,1> 

DNEXT  T 
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BAR    Fill  a  rectangle 


Syntax:      RUN  GFX2([path,rBAR"[,xcorl,ycorl),xcor2, 
ycorZ) 

Function:  Fills  a  rectangular  area  defined  by  two  sets  of  coor- 
dinates. BAR  defines  its  area  with  an  imaginary  diagonal 
line  from  the  first  set  of  coordinates  to  the  second  set  of  coor- 
dinates. The  X  coordinates  are  in  the  range  0-639.  The  Y 
coordinates  are  in  the  range  0-191. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

draw  a  bar. 

xcorl,ycorl  The  beginning  coordinates  of  the  line  defining 
the  area  to  fill.  If  you  omit  these  coordinates, 
BAR  uses  the  draw  pointer  position.  See  the 
previous  section  "The  Graphics  Cursor  and 
The  Draw  Pointer."  Also  see  SETDPTR. 

xcor2,ycor2  The  ending  coordinates  of  the  line  defining  the 
area  to  fill. 

Examples: 

RUN   GFX2C"BAR",200,100) 
RUN   GFX2<"BAR",0,0,100,50) 

Sample  Program: 

This  procedure  draws  a  bar  chart  on  a  window  screen. 

PROCEDURE  DSgraf 

DDIM  COLOR, T.X.XC0R1  ,YC0R1  .XC0R2 , YC0R2; 

INTEGER;  RESPONSE : STR I NG[ 1 ] 

GPRINT  CHRK12) 

DRUN  GFX2C"DEFC0L") 

JCOLQR-13    \    XCOR1=10    \    YCOR1-180 

GXCOR2-XCOR1+40 

QRUN    GFX2CCUR0FF") 
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□FDR   T=1    TO    10 

GREAD    YC0R2 

CRUN    GFX2<"CaLDR", COLOR) 

□RUN   GFX2C"BAR",XC0R1 ,YC0R1 ,XCOR2 , YC0R2) 

DRUN   GFX2("C0LDR",7) 

DRUN   GFX2("B0X",XCDR1 ,YC0R1 , XCDR2 , YCDR2) 

DC0L0R-C0I0R  +  1     \    XC0R1 -XCOR1 +50    \    XC0R2-XC0R1 +  40 

□NEXT    T 

□PRINT    \    PRINT   "  DS-9   Sales    Chart" 

DRUN    GFX2{"BDX",0,0,S1 0,180) 

QGET   *1 .RESPONSE 

CRUN   GFX2C"CURON") 

DPRINT    CHR$C12> 

□END 

□DATA    17  0,150,140,130,11 0,90,7  0,60,50,30 
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-t>li#lj-L    Ring  the  terminal  bell 


Syntax:      RUN  GFX2<"BELL") 

Function:  Rings  the  terminal's  bell  (produces  a  beep  through 
the  speaker). 

Parameters:  None 

Examples: 

RUN   OFX2("aELL") 
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BLNKON    Character  blink  on 
BLNKOFF     Character  blink  off 


Syntax:      RUN  GFX2([patfi,J"BLNKON") 
RUN  GFX2([patfi,]"BLNKOFF") 


Function:  Executing  BLNKON  causes  all  subsequent  charac- 
ters sent  to  a  window  on  a  hardware  screen  to  blink.  A  hard- 
ware screen  is  one  of  the  predefined  device  windows  /Wl 
through  /W7.  Executing  BLNKOFF  cancels  a  previous  blink 
command;  characters  already  blinking  continue  to  do  so.  Blink 
does  not  operate  on  graphics  windows. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

blink  characters. 

Examples: 

RUN   GFX2CBLNK0N") 
RUN   GFX2C"BLNK0FF") 


9-55 


BASIC09  Reference 


JjOLilJoW    Switch  bold  characters  on  or  off 


Syntax:      RUN  GFX2([path,]"B0LDSW"," switch") 


Function:  Causes  characters  to  display  in  either  regular  or 
bold  typeface.  The  default  is  regular  typeface.  BOLD  only 
works  on  graphics  screens. 

Parameters: 

path  The  route  to  the  window  in  which  you  want 

bold  characters. 

switch  Can  be  either  "ON"  or  "OFF."  If  switch  is 

"ON,"  subsequent  characters  are  bold.  If 
switch  is  "OFF,"  subsequent  characters  are 
not  bold. 

Examples: 

RUN   GFX2<"B0LDSW","DN") 

Sample  Program: 

This  procedure  demonstrates  the  BOLDSW  function  by  display- 
ing both  bold  and  normal  text  on  a  window  screen. 

PROCEDURE  bold 

□DIM  LINE:STRING 

DDIM  LETTER:STRINGC1 ] 

DDIM  T, J, K, FLAG; INTEGER 

□RUN  GFX2("CLEAR") 

□FLAG-1 

□FDR  T-1  TO  8 

□READ  LINE 

GFOR  J  =  1  TO.  LEN<LINE> 

CLETTER=MID$(L1NE,J,1> 

GIF  LETTERO"!"  AND  LETTER<>"#"  THEN 

3PRINT  LETTER; 

GENDIF 

GIF  LETTER="«"  THEN 

GFLAG-FLAG*-1 
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GIF  FLAG>0  THEN 

DRUN  GFX2C"BDLDSW","0FF") 

DELSE 

DRUN  GFX2("B0LDSW","0N"> 

DENDIF 

DENDIF 

DIF  LETTER="*"  THEN 

DPRINT  CHR$(34>; 

DENDIF 

□NEXT  J 

DPRINT 

DNEXT  T 

DPRINT  \  PRINT 

DEND 

DDATA  "This  is  a  demonstration  of" 

DDATA  "the  "Bold!  function  of" 

DDATA  "BASICQ9's  GFX2  module." 

DDATA  "Use  the  command" 

DDATA  "(RUN  GFX2(#B0LDSW# ,#0N#>  !" 

DDATA  "to  turn  boldface  on." 

DDATA  "Use  !RUN  GFX2(*B0LDSW# ,#DFF#)  !" 

DDATA  "to  turn  boldface  off" 
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BORDER    Set  the  border  color 


Syntax:      RUN  GFX2([path,]"BORDER", color) 

Function:  Resets  the  palette  register  that  affects  a  window's 
border  color  (Register  0)  to  the  specified  color  code.  For  infor- 
mation on  the  palette  and  on  screen  colors,  see  "The  Palette" 
and  Table  9.7  earlier  in  this  chapter. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

change  border  color. 

color  One  of  the  current  palette  colors.  Cobr  can  be 

either  a  constant  or  a  variable. 

Examples: 

RUN   GFX2("B0RDER",1 ) 

Sample  Program: 

This  procedure  lets  you  select  different  border  colors  by 
pressing  {T}  or  Q  to  select  higher  or  lower  color  codes. 
Press  Qj  to  end  the  procedure. 

PROCEDURE  border 

jDIM  COLOR: INTEGER 

jDIM  KEY:STRINGC1 ] 

jC0L0R=8 

jRUN  GFX2CCLEAR") 

ZIWH1LE  KEYo"qM  AND  KEY<>"Q"  DD 

HGET  #1  ,KEY 

GIF  KEY-"-"  OR  KEY THEN 

□COL0R=C0L0R~1 

DENDIF 

□IF  KEY-"+"  OR  KEY-";"  THEN 

□C0L0R-C0LOR+1 

□ENDIF 
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3IF    CDLD15    OR    COLOR<0   THEN    CDL0R=8 

CENDIF 

jRUN   OFX2<"B0RDER,,,CDLOR> 

J?UN   GFX2<"CURXY",0,0) 

DENDHHILE 

3END 
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JjOX    Draw  a  rectangle 


Syntax:      RUN  GFX2{  [pa  th,l"BOX"[,xcorl,ycorl], 
xcor2,ycor2) 

Function:  Draws  a  rectangle.  BOX  defines  its  area  with  an 
imaginary  diagonal  line  from  the  first  set  of  coordinates  to 
the  second  set  of  coordinates.  BOX  does  not  reset  the  draw 
pointer.  The  X  coordinates  are  in  the  range  0-639.  The  Y 
coordinates  are  in  the  range  0-191. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

draw  a  box. 

xcorl.ycorl  The  beginning  coordinates  for  the  line  that 
defines  the  rectangle  to  drawn.  If  you  omit 
these  coordinates,  BOX  uses  the  draw  pointer 
position. 

xcor2,cor2  The  ending  coordinates  for  the  line  that 

defines  the  rectangular  area  to  be  drawn. 

Examples: 

RUN   GFX2("B0X", 280,100) 
RUN   GFX2("BOX",0,0,100,50> 

Sample  Program: 

This  procedure  draws  a  series  of  progressively  smaller  boxes  of 
different  colors  on  a  window  screen.  Then,  it  rapidly  changes  the 
colors  of  the  boxes  to  produce  a  hypnotic  effect. 

PROCEDURE  hypbox 

DDIM  X.Y.X1  ,Y1  ,T,R, COLOR: INTEGER 

DDIM  KEY:5TRINGM  ] 

DKEY 

DX-18    \Y-6 
DY1=18S    \X1-621 
DRUN   GFX2<"CL£AR"> 

9-60 


Displaying  Text  and  Graphics  I  9 


DFOR   T-0    TO    15 

QCOLOR-T 

CRUN   GFX2("C0L0R",3) 

CRUN   GFX2("B0X",X,Y,X1  ,Y1> 

GRUN   GFX2("C0L0R", COLOR) 

ORUN   GFX2C"FILL",X-1 ,Y-1> 

DX«X*18    \Y-Y*6 

DX1-X1-18    SY1-Y1-6 

DNEXT   T 

DWHILE    KEY«""  DO 

GRUN    INKEYCKEY) 

CFOR   T=1    TO    16 

GR"RND(65) 

CRUN   GFX2<,,PALETTE",T,R> 

CNEXT   T 

CENDWHILE 

CRUN    GFX2CDEFCDL") 

GEND 
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\s\.ixK/LjEj    Draw  a  circle 


Syntax:      RUN  GFX2([path,]"CIRCLE"[,xcor,ycor], 

radius) 

Function:  Draws  a  circle  with  a  specified  radius.  If  you  specify 
coordinates,  CIRCLE  uses  them  for  the  center  point.  Other- 
wise, CIRCLE  locates  the  center  of  the  circle  at  the  current 
draw  pointer  position.  See  "The  Graphics  Cursor  and  the 
Draw  Pointer"  earlier  in  this  section.  Also  see  SETDPTR. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

draw  a  circle. 

xcor,ycor  The  coordinates  for  the  circle's  center.  The  X 

coordinates  are  in  the  range  0-639.  The  Y 
coordinates  are  in  the  range  0-191. 

radius  The  radius  of  the  circle. 

Examples: 

RUN  GFX2C"CIRCLE",1  00> 

RUN  GFX2("CIRCLE", 100,200,50) 
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Sample  Program: 

This  procedure  uses  circles  to  produce  a  geometric  design. 

PROCEDURE    clraround 

DDIM   T,X,Y:  INTEGER 

DPRINT   CHR$C12J 

DRUN    GFX2C"CDLDRM,1 ,2) 

LiFOR   T-1    TO    130 

[]X«1S0*SIN(T>  +  320 

CY=25*C0S(T>+96 

DRUN   GFX2("CIRCLE",X,Y,100> 

DNEXT   T 

DRUN   GFX2<"C0L0R",3,2> 

HFOR   T=1    TO    45 

DX=150»SIN<T>*320 

0Y-25«COS(T)+9G 

DRUN   GFX2<"CIRCLE,\X,Y,100) 

DNEXT    T 

jEND 
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CLEAR     Clear  the 


screen 


Syntax:      RUN  GFX2([path,]"CLEAR") 

Function:  Clears  the  current  working  area  of  a  window. 
CLEAR  does  not  change  the  location  of  the  draw  pointer  but 
does  set  the  text  cursor  and  graphics  cursor  location  to  the 
upper  left  corner  of  the  window. 

Parameters: 

path  The  route  to  the  window  you  want  to  clear. 

Examples: 

RUN   GFX2<"CLEAR") 
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OOJ-iOxv    Set  screen  colors 


Syntax:      RUN  GFX2([path,]"COLORn, 

foregroundl,  background]  [,  border]) 


Function:  Changes  any  of  the  foreground,  background,  or  the 
border  colors.  COLOR  does  not  change  the  draw  pointer 
position. 


Parameters: 

path 

foreground 

background 

border 


The  route  to  the  window  in  which  you  want  to 
change  one  or  more  screen  or  text  colors. 

The  register  number  for  the  foreground 
palette. 

The  register  number  for  the  background 
palette. 

The  register  number  for  the  border  palette. 
Changing  the  border  color  for  any  window  on  a 
screen,  changes  the  border  color  for  all  win- 
dows on  the  same  screen. 


Examples: 

RUN   GFX2C"C0t0R",1 ) 
RUN   GFX2("CDLDR",1 ,2) 
RUN   GFX2<"CQLQR",1 ,2,1) 
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Sample  Program: 

This  procedure  fills  a  window  screen  with  multicolored  filled 
circles. 

PROCEDURE  bubblea 

DDIM  X,Y,W,Z,T:INTEGER 

DZ-1 

DRUM  GFX2("CDLDR",1 ,0,0) 

DRUN  GFX2C"CLEAR"> 

DFDR  T-1  TO  80 

DX»RND(63S>*4 

aY«RND(185)+5 

QW-RNDCS0+5) 

JZ=Z*\ 

HIF  Z>3  THEN  2-1 

DENDIF 

DRUN  GFX2<,,CIRCLE,\X,Y,W> 

GRUN  GFX2<"C0L0R,,,Z) 

IRUN  GFXaCFILL-'.X.YJ 

CNEXT  T 

CRUN  GFX2("C0L0R",3,2,2> 

CEND 
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O XV  Jv  I N    Carriage  return 


Syntax:      RUN  GFX2([patfi,]"CRRTN") 


Function:  Causes  BASIC09  to  send  a  carriage  return  to  a 
window.  The  cursor  moves  down  one  line  and  to  the  extreme 
left  of  the  window. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  a 

carriage  return. 

Examples: 

RUN    GFX2("CRRTN") 
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CURDWN    Cursor  down 


Syntax:      RUN  GFX2([pa6a,3"CURDWN") 

Function:  Moves  the  cursor  down  one  text  line.  The  X-coordi- 
nate,  or  column  position,  remains  the  same. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

move  the  cursor. 

Examples: 

RUN   GFX2("CURDWN") 


9-68 


Displaying  Text  and  Graphics  I  9 


CURHOME     Cursor  home 


Syntax:      RUN  GFX2([pa«it]"CURHOME") 

Function:  Moves  the  text  cursor  to  the  top  left  corner  of  the 

screen. 

Parameters: 

path  The  route  to  the  window  where  you  want  to 

reset  the  cursor 

Examples: 

RUN    GFX2("CURH0ME"> 
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O  U xvl^r  1     Move  cursor  left 


Syntax:      RUN  GFX2([pat/.,]"CURLFT") 

Function:  Moves  the  cursor  one  character  to  the  left. 

Parameters: 

path  The  route  to  the  window  where  you  want  to 

move  the  cursor. 

Examples: 

RUN  GFX2<"CURLFT"> 
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CUROFF     Turn  off 


cursor 


Syntax:      RUN  GFX2([patA,;rCUROFF") 

Function:  Makes  the  cursor  invisible. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

turn  the  cursor  off. 

Examples: 

RUN   GFX2("CUR0FF"> 
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OUxvON    Turn  on  cursor 


Syntax:      RUN  GFX2([pa£h,]"CURON") 


Function:  Makes  the  text  cursor  visible. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

turn  the  cursor  on. 

Examples: 

RUN   GFX2("CUR0N"J 
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O  U  -KKCjt  1     Move  cursor  right 

Syntax:      RUN  GFX2("[pa*Ii,]CURRGT") 

Function:  Moves  the  cursor  one  character  to  the  right. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

move  the  cursor. 

Examples: 

RUN   GFX2CCURRGT") 
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O  U  XvU  -P    Move  cursor  up 


Syntax:      RUN  GFX2([patfi,]"CURUP") 


Function:  Moves  the  cursor  up  one  line. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

move  the  cursor. 

Examples: 

RUN    GFX2CCURUP") 
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•*-. 


Is  U  Jv A.  Y     Set  cursor  position 


Syntax:      RUN  GFX2([pa  tfj,]"CURX Y">Column,row) 

Function:  Moves  the  cursor  to  the  specified  column  and  row 
position.  The  column  and  row  coordinates  are  relative  to  the 
window's  current  character  width  and  depth. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

move  the  cursor. 

column  The  column  (horizontal)  position  for  the 

cursor. 

row  The  row  (vertical)  position  for  the  cursor. 

Examples: 

RUN   CFX2<"CURXY,,,18,10) 
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C-  WA.  IX  hj  A.    Change  working  area 


Syntax:      RUN  GFX2([path,Y'CWAREA",xcor,ycor,sizex, 

sizey) 


Function:  Restricts  output  in  the  window  to  the  specified  area. 
The  new  area  must  be  the  same  or  smaller  than  the  previous 
working  area.  When  a  window's  working  area  is  changed, 
OS-9  scales  graphic  and  text  coordinates  and  graphic  images 
to  the  new  proportions.  Text  characters  remain  the  same  size. 


Parameters: 

path 

xcor,ycor 


sizex 


sizey 


The  route  to  the  window  in  which  you  want  to 
change  the  working  area. 

The  beginning  coordinates  (the  upper  left  cor- 
ner) for  the  new  working  area,  relative  to  the 
original  window.  The  coordinates  are  based  on 
the  character  column  and  row  size  of  the  origi- 
nal window. 

Designates  the  number  of  columns  in  the  new 
working  area. 

The  number  of  lines  available  in  the  new 
working  area. 


Examples: 

RUN   GFX2("CWAREA",10, 0,40,18) 
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Sample  Program: 

This  procedure  makes  the  working  area  in  a  window  progres- 
sively smaller,  filling  each  area  with  a  different  color.  It  then 
changes  the  areas'  colors  rapidly  to  produce  a  hypnotic  effect. 

PROCEDURE  hypnobox 

DDIM  X,Y,X1 ,Y1 ,T,R, COLOR: INTEGER 

DDIM  KEY:STRINGM  ] 

CKEY 

GX=3  \Y-1 

3X1 -80-CX+X)  \Y1=24-<Y+Y) 

3F0R  T-0  TO  10 

DRUN  GFX2("C0L0R,,,3,T> 

DRUN  GFX2C"CLEAR"> 

DRUN  GFX2<"CWAREA",X,Y,X1 ,Y1) 

DX-X+3  \Y-Y+1 

DX1=80-<X*X>  SY1-24-CY+Y) 

DNEXT  T 

DRUN  GFX2<"COL0R",3,2) 

DWHILE  KEY-""  DO 

DRUN  INKEYCKEY) 

□FOR  T-1  TO  16 

CR=RND<65) 

CRUN  GFX2{"PALETTE",T,R> 

jNEXT  T 

DENDWHILE 

DRUN  GFX2<"DEFCOL") 

DRUN  GFX2C"CWAREA",0,0,80,24> 

DEND 
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DEFBUFF    Define  GET/PUT  buffer 


Syntax*.      RUN  GFX2("DEFBUFF",group,i>uffer,size) 


Function:  Defines  a  buffer  for  GET/PUT  operations. 

When  you  define  a  buffer,  you  do  so  by  group  number  and 
buffer  number.  Each  group  you  define  allocates  eight  kilobytes 
of  memory.  The  system  needs  30  bytes  of  the  block  for  over- 
head, leaving  8162  bytes  free.  Within  the  group,  you  can  allo- 
cate one  or  more  buffers.  Select  a  group  number  and  a  buffer 
number  as  indicated  in  the  following  "Parameters"  section. 
Use  these  numbers  in  future  references  to  the  buffer. 

A  GET/PUT  buffer  remains  allocated  until  you  use  the  KILL- 
BUFF  function  to  remove  it  from  your  system's  memory.  For 
more  information  on  Get/Put  buffers,  see  KILLBUFF,  PUT, 
GET,  and  GPLOAD. 

Parameters: 

group  A  number  you  select  in  the  range  1-199. 

buffer  A  number  (in  the  range  1-255)  that  you 

assign  to  the  buffer  you  create. 

size  The  size  of  the  buffer,  in  the  range  of  1  to 

8192  bytes,  depending  on  available  memory  in 
its  group. 

Notes: 

One  method  of  selecting  a  group  number  is  to  use  SYSCALL 
and  the  Get  ID  {103F  OC)  system  call  to  obtain  your  user's 
process  ID  number.  Then,  use  this  ID  number  as  a  group 
number.  Using  this  system  for  all  GET/PUT  buffer  operations, 
ensures  against  group  number  overlapping.  See  the  SYS- 
CALL command  for  more  information. 

Examples: 

RUN  GFX2("DEFBUFF,,,1  ,5,4000H0> 
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DEFCOL    Set  default  colors 


Syntax:      RUN  GFX2([patfi,]"DEFCOL") 


Function:  Sets  the  palette  registers  back  to  their  default  val- 
ues. The  type  of  monitor  you  have  determines  the  actual  hues. 
See  'The  Palette"  and  Table  9,7  earlier  in  this  section. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

restore  the  original  palette  registers. 

Examples: 

RUN  GFX2C"DEFC0L"> 
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DE LLIN    Delete  current  line  of  text 


Syntax:      RUN  GFX2([pa*h,]"DELLIN") 

Function:  Deletes  the  line  on  which  the  cursor  is  resting  and 
closes  the  space.  DELLIN  operates  on  both  text  and  graphics 
screens. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

delete  a  line. 

Examples: 

RUN   GFX2C"DELLIN") 

Sample  Program: 

This  procedure  draws  a  series  of  various  colored  concentric  cir- 
cles, then  produces  a  lemon  shape  by  removing  slices  of  the  circle 
with  DELLIN. 

PROCEDURE  slice 

DDIM  X,Y,R,T, COLOR: INTEGER 

DRUN   GFX2<"CLEAR") 

DCOLOR-0 

DX=320 

DY=96 

DFOR   T=185   TO    10    STEP    -10 

DRUN   GFX2<"CIRCLE",X,Y,T) 

DNEXT   T 

CFOR  T-140  TO  320  STEP  10 

DRUN  GFX2C"C0L0R", COLOR) 

DRUN  GFX2("FILL,',T,9G) 

CC0L0R-COLOR+1 

DNEXT  T 

DRUN  GFX2<"CURXY",0,8> 

CFQR  T=1  TO  8 

:run  GFX2C"DELLIN") 

liNEXT  T 

JRUN  GFX2("C0L0R",3,2) 

DEND 
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DxCAW     Draw  a  polyline  figure 


Syntax:      RUN  GFX2(lpath,)"DRAW', option  list) 


Function:  Draws  in  the  directions  specified,  and  for  the  dis- 
tances specified,  in  an  option  list.  The  option  list  is  a  string  of 
characters  and  numbers.  You  can  separate  options  with  spaces 
or  commas.  You  must  include  commas  between  the  two  coordi- 
nates for  the  B  and  U  options. 


Parameters: 

path 

option  list 


The  route  to  the  window  in  which  you  want  to 
draw. 

A  string  consisting  of  one  or  more  of  the  fol- 
lowing options: 


Options: 

Nnum 

Snum 

'Enum 

Wnum 

NEnum 

NWnum 

SEnum 

SWnum 

Aval 


XJxcorycor 


draws  north  (up)  num.  units. 

draws  south  (down)  num.  units. 

draws  east  (right)  nam  units. 

draws  west  (left)  num.  units. 

draws  northeast  (up  and  right)  num.  units. 

draws  northwest  (up  and  left)  num  units. 

draws  southeast  (down  and  right)  num  units. 

draws  southwest  (down  and  left)  num  units. 

rotates  the  draw  axis.  Possible  values  are: 

0  =  normal 

1  =  90  degrees 

2  =  180  degrees 

3  =  270  degrees 

draws  a  relative  vector  to  the  specified  coordi- 
nates. Xcor  and  ycor  are  relative  to  the  cur- 
rent draw  pointer  position.  The  draw  pointer 
location  does  not  change.  Xcor  and  ycor  must 
be  separated  by  a  comma. 
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Bxcor,ycor  produces  a  blank  line  (moves  the  cursor  but 
does  not  draw).  The  xcor  and  ycor  coordinates 
are  relative  to  the  current  draw  pointer  loca- 
tion. If  you  specify  relative  coordinates  located 
offscreen,  you  cannot  see  subsequent  lines. 

Examples: 

RUN   GFX2<"DRAW" ,"N1 0  ,  E1 0 , S1 0 ,W1 0") 

Sample  Program: 

PROCEDURE  drawing 

CDIM  T,X,Y, COLOR: INTEGER 

CCOLOR-0 

DRUN  GFX2C"CLEAR"> 

DFOR  T=1  TO  96  STEP  6 

DRUN  GFX2t"SETDPTR",320,96> 

DFOR  Y-0  TO  3 

~C0LDR-MQD(Y,2) 

CRUN  GFX2("C0L0R,,,C0L0R) 

DFOR  X=1  TO  4 

DREAD  DR* 

DDR$-"fl,,  +  STR$<Y)  +  DR$*STR*(T) 

DRUN  GFX2("DRAW",DR$) 

DNEXT  X 

DNEXT  Y 

DRESTORE 

DNEXT  T 

L"RUN  GFX2C"C0L0R,,,3) 

CEND 

ODATA  "N",,,E","S","W" 
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DWEND    Device  window  end 


Syntax:      RUN  GFX2([pata,]"DWEND") 


Function:  Deallocates  the  device  window  you  initialized  with 
DWSET  and  INIZ.  If  the  window  deallocated  is  the  last  device 
window  on  the  screen,  BASIC09  returns  the  screen  memory  to 
the  system.  DWEND  automatically  positions  you  in  the  next 
device  window,  a  result  similar  to  pressing  I  clear  |.  You  can 
use  this  function  with  DWSET  to  redefine  a  device  window  to 
a  different  type. 

Parameters: 

path  The  path  number  of  the  window  you  wish  to 

end.  Path  can  be  a  constant  or  variable. 

Examples: 

RUN   GFX2C"DWEND") 

RUN  GFX2<PATH, "DWEND") 
RUN  GFX2<3, "DWEND") 

Sample  Program: 

From  /TERM,  this  procedure  temporarily  opens  a  path  to 
Window  3,  displays  the  new  window,  draws  a  design,  then 
returns  to  the  /TERM  screen  and  closes  the  path. 

PROCEDURE  decorate 

CDIM  PATH,T,Y:INTEGER 

CDPEN  #PATH,"/W3,,:WRITE 

CRUN  GFX2<PATH,,,DWSET,',7,0,0,80,24,3,2,2) 

TRUN  GFX2CPATH, "SELECT") 

CY  =  1 

CRUN  GFX2<PATH,"C0L0R",3,2> 

DFDR  T-1  TD  185  STEP  3 

DY-Y+1 

DRUN  GFX2CPATH,"ELLIPSE",320,96>T,Y) 

DNEXT  T 

DRUN  GFX2CPATH,"C0LDR",1 ,2) 

QFDR  T-185  TD  1  STEP  -G 
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DRUN   GFX2CPATH,"ELLIPSE,,,320,96,T,Y) 

DIF    INT(T/3)-T/3   THEN 

DY=Y+1 

DENDIF 

DNEXT   T 

DRUM   GFX2(1 ."SELECT") 

DRUN    GFX2(PATH,"DWEND"> 

DCLOSE    #PATH 

GEND 
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JJW.Pxv(J  1  O  W    Device  window  protect  switch 


Syntax:      RUN  GFX2([pati,]"DWPR0TSW"," switch") 

Function:  Lets  you  unprotect  one  device  window  and  set  other 
device  windows  on  top  of  it, 

OS-9  on  the  Color  Computer  3  normally  uses  a  protected  win- 
dowing system  that  does  not  allow  window  devices  to  overlap. 
Removing  the  window  protection  with  DWPROTSW  lets  one 
device  window  exist  on  the  same  screen  area  as  another  win- 
dow device.  Because  this  might  destroy  the  contents  of  an 
unprotected  window,  you  need  to  use  care  with  this  function. 

Parameters: 

path  The   route   to    the    window   you    want   to 

unprotect. 

switch  Either  OFF  to  turn  off  protection,  or  ON  to 

turn  on  protection.  The  default  is  ON. 

Examples: 

RUN  GFX2C"DWPRDTSW",QFF) 
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IJWbJli  X     Device  window  set 


Syntax:      RUN  GFX2([path,]"DWSET",format,xcor,ycor, 
width,lengtb,  foreground,  background,  border) 


Function:  Defines  a  device  window.  Normally,  you  first  open  a 
path  to  a  window,  then  use  DWSET  to  set  the  window  format, 
location,  size,  and  colors. 


Parameters: 

path 
format 

xcorjcor 

width 

length 

foreground 

background 

border 

Examples: 


The  route  to  the  window  you  are  defining, 

The  code  for  the  type  of  screen  you  want  to 
establish.  See  Table  9.6  at  the  beginning  of 
this  section  for  the  formats  available. 

The  coordinates  (character  column  and  row)  of 
the  upper  left  corner  of  the  screen  you  want  to 
create. 

The  width  (in  characters)  of  the  new  window. 

The  depth  (in  lines)  of  the  new  window. 

The  code  for  the  window's  foreground  color. 

The  code  for  the  window's  background  color. 

The  code  for  the  window's  border  color. 


RUN    GPX2( "DWSET", 06,50,1 00,50,10,20,12,9) 

Sample  Program: 

This  procedure  opens  a  path  to  Window  3,  uses  DWSET  to  define 
the  new  window,  displays  the  new  window,  and  draws  a  graphic 
lemon  shape.  It  then  uses  SELECT  to  return  to  the  /TERM  win- 
dow or  screen,  deallocates  Window  3,  and  closes  the  path. 
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PROCEDURE  lemon 

CDIM  PATH, T,X,Y: INTEGER 

DOPEN  #PATH,"/W3":WRITE 

DRUN   GF X2< PATH, "DWSET" ,7,0,0,80,24,3,2,2) 

DRUN   GFX2CPATH,"SELECT") 

DY-1 

DRUN   GFX2CPATH,,,COLOR",0,2) 

DFOR   T=1    TO    185    STEP    3 

DY=Y+1 

DRUM   GFX 2C PATH, "ELL  IPSE", 32  0, 96, T,Y) 

DNEXT   T 

DX=T 

DRUN   GFX2<PATH,"CDLDR",3,2) 

DFDR   T*62   TO    1    STEP    -3 

DRUN   GFX2(PATH,"ELLIPSE",320,96,X,T) 

DIF  INTCT/3>-T/3  THEN 

DX=X*1 

DENDIF 

DNEXT   T 

DRUN   GFX2C1 , "SELECT") 

IRUN   GFX2CPATH,"DWEND") 

LCLOSE  #PATH 

CEND 
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vj  I  j  I  jL  if  Oii<    Draw  an  ellipse 


Syntax:      RUN  GFX2([paiii,]"ELLIPSE"[,xcor,ycor]( 
xrad,yrad) 

Function:  Draws  an  ellipse  with  the  center  at  the  current 
draw  pointer  position  or  at  the  specified  X,Y  coordinates.  The 
X  coordinates  are  in  the  range  0-639.  The  Y  coordinates  are 
in  the  range  0-191. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

draw. 

xcorjcor  The  coordinates  for  the  ellipse's  center.  If  you 

omit  these  coordinates,  ELLIPSE  uses  the 
current  draw  pointer  position. 

xrad,yrad  The  radii  of  the  ellipse's  length  and  height. 

Examples: 

RUN   GFX2("ELLIPSE",1  00,50) 

RUN  GFX2C"ELLIPSE", 100,125,100,10) 

Sample  Program: 

This  program  uses  ELLIPSE  to  draw  a  graphic  design  shaped 
like  a  Christmas  tree  decoration. 

PROCEDURE  xbulb 

DDIM  T,Y: INTEGER 

DY=1 

DRUN  GFX2< "COLOR", 3,2) 

CRUN  GFX2("CLEAR"> 

CFOR  T-1  TD  180  STEP  3 

CY-Y+1 

CRUN  GFXaC'ELLIPSE" ,320,96,T,Y> 

GNEXT  T 

QRUN  GFX2("C0L0R",1  ,2) 

DFOR  T-1 80  TO  1  STEP  -6 
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DRUN   GFX2<"ELL IPSE", 320, 9G,T,Y) 

GIF    INT(T/3)=T/3   THEN 

HY=Y+1 

DENDIF 

DNEXT   T 

3RUN   0FX2C"C0L0R",3,2) 

ZEND 
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E  RE OLINE    Erase  to  end  of  line 


Syntax:      RUN  GFX2([patfi,]"ERE0LINE") 


Function:  Deletes  the  portion  of  the  current  line  from  the  cur- 
sor to  the  right  side  of  the  window. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

erase  a  portion  of  a  line. 

Examples: 

RUN  GFX2C"ERE0LINE") 

Sample  Program: 

This  procedure  uses  EREOLINE  to  produce  a  series  of  steps 
down  the  screen. 

PROCEDURE    steps 
QDIM   T, J, K: INTEGER 
DRUN   GFX2<"C0L0R*\2,3) 
DRUN   GFX2<"CLEAR"> 
CRUN   GFX2<"CDL0R",3,2) 
CF0R   T-0    TO    22 
CJ=T*3 

CRUN   GFX2C"CURXY" ,J,T) 
GRUN    OFX2("ERE0UNE"> 
DNEXT   T 
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ERE OWNDW    Erase  to  end  of  window 


Syntax:      RUN  GFX2([jpafii,]"EREOWNDW") 

Function:  Deletes  all  the  lines  in  a  window  from  the  line  on 
which  the  cursor  is  positioned  to  the  bottom  of  the  window. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

delete  screen  contents. 

Examples: 

RUN  GFX2("ERE0WNDW"> 
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E  RLINE    Delete  current  line  of  text 


Syntax:      RUN  GFX2([patfi,]"ERLINE") 

Function:  Deletes  the  current  line  (on  which  the  cursor  is  rest- 
ing) from  the  window  but  does  not  close  the  space, 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

remove  the  contents  of  a  screen  line. 

Examples: 

RUN   GFX2<"ERLINE") 

Sample  Program: 

This   procedure   draws    a    bull's-eye   design,    then   slices   it 
with  the  ERLINE  function. 

PROCEDURE  cut 

DDIM  X.Y.R.T.COLOR: INTEGER 

DCOL0R=8 

DX-320 

DY-96 

DRUM  GFXZC'CLEAR") 

DCOLDR=0 

DFDR  T=18S  TO  10  STEP  -10 

DRUN  GFXaC'CIRCLE-.X.Y^) 

DNEXT  T 

DFDR   T-140    TO   320    STEP    10 

DRUN   GFX2t"C0L0R",CDLDR) 

DRUN   GFX2t"FILL",T,96) 

CCOLOR-COLDR+1 

GNEXT  T 

GFOR  T-2  TO  22  STEP  2 

GRUN  GFX2C"CURXY,,)0,T) 

3RUN  GFX2("ERLINE") 

GNEXT  T 

CRUN  GFX2(,,COL0R",3,2) 

GEND 
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r  IJ-i-L*    Fill  {paint)  window 


Syntax:      RUN  GFX2([pafco,]"FILL",[xcor,ycor]) 

Function:  Paints  an  area  with,  the  current  foreground  color. 
Paint  fills  the  portion  of  the  window  that  is  the  same  color  as 
the  pixel  under  the  draw  pointer. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

use  the  FILL  function. 

xcor,ycor  Are  optional  X-  and  Y-coordinates  to  reposi- 

tion the  draw  pointer  before  FILL  begins.  If 
you  omit  these  coordinates,  BASIC09  uses  the 
current  draw  position. 

Examples: 

RUN    GFX2C"FILL", 100,1 00) 

Sample  Program: 

This  procedure  draws  and  fills  100  boxes  on  a  window. 

PROCEDURE  colorbox 

GDIM  A, B,C,D,T, COLOR: INTEGER 

DCDLOR-0 

DRUN  GFX2("CLEAR"> 

DFOR  T=1  TO  100 

DA=RNDC560) 

DB-RNDC151 > 

DC-A*RNDC80> 

JD-B+RNDC40) 

HC0L0R=C0L0R*1 

DRUN  GFX2«"C0L0R", COLOR) 

CRUN  GFX2("B0X",A,B,C,D) 

DRUN  GFX2<"FILL",A+1  ,B+1) 

DNEXT  T 
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FONT     Define  font  buffer 


Syntax:      RUN  GFX2([path,]"FONT',group,buffer) 

Function:  Defines  a  buffer  from  which  BASIC09  gets  the  char- 
acter font  (style)  for  the  current  screen.  Use  the  text/cursor 
handling  functions  referenced  in  this  section  with  the  font  you 
load.  When  you  merge  the  Stdfonts  file  in  your  SYS  directory 
with  a  graphics  window,  you  have  the  choice  of  three  fonts 
from  Buffers  1,  2,  and  3,  located  in  Group  200.  You  can  also 
create  your  own  fonts.  FONT  works  only  on  graphics  screen. 
See  "Using  Fonts"  earlier  in  this  chapter. 

You  must  load  the  font  you  want  to  use  into  the  defined  buffer 
before  using  FONT. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

use  an  alternate  font. 

group  The  group  number  of  the  buffer  containing  the 

font  to  use. 

buffer  The  number  of  the  buffer  containing  the  font 

to  use. 

Examples: 

RUN   OFX2<"FDNT", 200,2) 
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GC  SE  T    Set  graphi 


cs  cursor 


Syntax:      RUN  GFX2("GCSET", group,buffer) 

Function:  Defines  a  buffer  from  which  BASIC09  gets  the 
graphics  cursor.  This  lets  you  define  your  own  cursor  for 
graphics  operations.  To  turn  the  graphics  cursor  off,  use  a 
group  Number  0.  You  must  execute  this  command  to  display  a 
graphics  cursor.  Before  using  GCSET,  you  must  merge  the 
Stdcur  file  in  the  SYS  directory  to  the  window. 

Parameters: 

group  The  group  number  of  the  buffer  containing  the 

cursor  image  to  use.  See  OS-9  Windowing 
System  for  information  on  the  group  to  use. 

buffer  The  number  of  the  buffer  that  contains  the 

cursor  image  to  use.  See  OS-9  Windowing 
System  for  information  on  the  buffer  to  use. 

Examples: 

RUN   GFX2C"GCSET",1 ,5) 
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CxEj  X     Get  a  block  from  the  window 


Syntax:       RUN  GFX2([path,]"GET\group,buffer,xcor, 
ycor,xeize,ysize) 


Function:  Saves  a  window  area  Get/Put  buffer.  Use  PUT  to 
replace  the  image  to  the  window.  If  you  did  not  previously 
define  the  buffer,  BASIC09  creates  it.  If  you  store  the  window 
data  in  a  predefined  buffer,  the  data  must  be  the  same  size  or 
smaller  than  the  buffer.  If  not,  BASIC09  truncates  the  data  to 
the  size  of  the  buffer.  (Also  see  PUT  and  DEFBUFF.) 


Parameters: 

path 

group 

buffer 
xcorycor 


xsize 


ysize 


The  route  to  the  window  where  you  want  to 
save  an  image. 

The  group  number  of  the  Get  buffer  (1-199). 

The  Get  buffer  number  (1-255). 

The  X-  and  Y-coordinates  of  the  upper  left  cor- 
ner of  the  window  image  to  save.  The  X- 
coordinates  are  in  the  range  0-639.  The  Y- 
coordinates  are  in  the  range  0-191. 

The  horizontal  size  of  the  window  section  to 
save. 

The  vertical  size  of  the  window  section  to  save. 


Examples: 

RUN   GFX2<"GET",1 ,5,0,0,10,15) 
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Sample  Program: 

This  procedure  draws  a  character,  loads  it  into  a  buffer,  then 
repeatedly  replaces  the  character  to  the  window  screen  using 
PUT.  Each  new  image  erases  the  previous  image,  giving  an 
impression  of  animation. 

PROCEDURE  puttdown 

DDIM  T,J: INTEGER 

DRUN  GFX2<,,CLEAR") 

DRUN  GFX2( "ELL  IPSE" ,320,96, 12,  4  J 

DRUN  GFX2<"C!RCLE,\320,90,5) 

DRUN  GFX2("CDLDR",1) 

DRUN  GFX2("FILL",320,96) 

DRUN  GFX2("C0L0R",3) 

DRUN  GFX2C"FILL",320,90) 

DRUN  GFX2C"BAR", 305, 100, 335,1 04) 

DRUN  GFX2("GET",1 ,1 ,288,85,50,23) 

DRUN  GFX2<"GET",1 ,2,1 ,1 ,50,23) 

DRUN  GFX2<"PUT",1 ,2,288,85) 

DJ  =  10 

DFOR  T=20  TO  559  STEP  6 

L\J-J*2 

DRUN  GFX2<"PUT",1  ,1  ,T,J) 

DNEXT  T 

DRUN  GFX2("KILLBUFF",1 ,1  ) 

DRUN  GFX2CCUR0N") 

DEND 
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GPLOAD    Load  data  into  Get/Put  buffer 


Syntax:       RUN  GFX2("GPLOAD",group,buffer,format, 
xdimtydim,size) 


Function:  Loads  a  buffer  with  image  data  that  PUTBLK  can 
use  for  window  displays.  If  the  Get/Put  buffer  is  not  created, 
BASIC09  creates  it.  If  it  is  defined,  the  size  of  the  data  should 
not  be  larger  than  the  buffer. 


Parameters: 

group 

buffer 

format 

xdim 

ydim 
size 


The  group  number  you  select,  in  the  range  1- 
199,  to  let  you  group  buffers. 

A  number  in  the  range  1-255  that  you  assign 
to  the  buffer  you  create. 

The  type  code  of  the  screen  format.  (See  Table 
9.4.) 

The  X  (horizontal)  dimension  of  the  stored 
block. 

The  Y  (vertical)  dimension  of  the  stored  block. 

The  size  of  the  buffer  in  bytes.  A  buffer  size 
can  be  in  the  range  of  1  to  8  kilobytes, 
depending  on  available  memory. 


Examples: 

RUN   GFX2("DEFBUFF",1 , 5 , 06 , 1 80 , 50 , 5000 ) 
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INSLIN    Insert  line 


Syntax:      RUN  GFX2([patA,]"INSLIN") 


Function:  Moves  the  window  lines  at  and  below  the  cursor 
down  one  line. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  a 

blank  line. 

Examples: 

RUN  GFX2<"INSLIN"> 

Sample  Program: 

This  procedure  draws  a  round  face  on  the  screen,  then  uses 
INSLIN  and  DELLIN  to  make  a  mouth  appear  to  move. 

PROCEDURE    chomp 

DDIM    X,Y,T:INTEGER 

DDIM  RESPONSEiSTRINGtl] 

jRESPONSE-"" 

DRUN  GFX2("CLEAR"> 

DRUN  GFX2("CIRCLE", 320, 96,80) 

DRUN  GFX2<"COLQR,,,0,2) 

DRUN  GFX2<"FILL",320,96) 

DRUN  GFX2C"C0LDR",2) 

DRUN  GFX2C"CIRCLE", 285,80, 12) 

DRUN  GFX2C"CIRCLE",355,80,12) 

CRUN  GFX2<"FILL",285,80) 

CRUN  GFX2<"FILL",355,80) 

[]RUN  GFX2{"CIRCLE", 315, 96,3) 

ZiRUN  GFX2("CIRCLE", 325, 96,3) 

DRUN  GFX2("ARC",320,92,14J3,3,1 ,1,1) 

DRUN  GFX2C"CDLDR",3,2) 

DRUN  GFX2C"CIRCLE,,,289,7?,3) 

CRUN  GFX2<"CIRCLE",359,77,3) 

CRUN  GFX2("CURXY,,,0,14) 

ZiREPEAT 
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DRUN    GFX2CIN5LIN") 

QFOR    X-1    TO    100 

DNEXT    X 

DRUN   OFX2<"DELLIN"> 

DRUN    INKEY(RESPONSE) 

DUNT1L    RESPONSE)"" 

DEND 
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KILLBUFF    Deallocate  Get/Put  buffer 


Syntax:      RUN  GFX2("KILLBUFF", group,buffer) 

Deallocates  the  indicated  Get/Put  buffer.  Ya\i  select  group  and 
buffer  numbers  when  you  define  a  buffer  or  when  you  load  or 
get  a  window  image.  For  more  information  on  Get/Put  buffers, 
see  DEFBUFF,  PUT,  GET,  and  GPLOAD. 

Parameters: 

group  The  group  number  of  the  buffer  you  want  to 

deallocate,  in  the  range  1-199.  Buffer  Group 
Numbers  0  and  200-255  are  reserved  for  OS-9 
system  use. 

buffer  The  number  of  the  buffer  to  deallocate,  in  the 

range  1-255. 

Examples: 

RUN  GFX2<"KILtBUFF",1 ,5) 

Sample  Program: 

This  procedure  draws  a  figure  on  a  window  screen,  loads  it 
into  a  buffer,  then  repeatedly  places  it  in  new  locations  on  the 
screen.  Each  new  PUT  erases  the  previous  image. 

PROCEDURE  putdown 

DDIM  X,Y,T,J: INTEGER 

DRUN  GFX2<"CUROFFM) 

GRUN  GFX2("CLEAR") 

GRUN  GFX2C"ELLIPSE",320,9G,12,4) 

GRUN  GFX2("CIRCLE",320,90,5) 

DRUN  GFX2("C0LDR",1) 

GRUN  GFX2C"F!ll",320,96) 

DRUN  GFX2("C0L0R",3) 

GRUN  GFX2("FILL,,,320,90) 

DRUN  GFX2("BAR" , 385 , 1 00 , 335 , 1  04) 

DRUN  GFX2("GET",1 ,1 ,288,85,50,23) 

DRUN  GFX2C"GETM,1 ,2,1 ,1  ,50,23) 

DRUN  GFX2("PUT",1 ,2,288,85) 
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CJ  =  1  0 

CFOR  T=20  TO  559  STEP  6 

DJ-J+2 

DRUN  GFX2("PUT",1 ,1 ,T,JJ 

DNEXT  T 

CRUN  GFX2C"KILLBUFF,\1  ,1> 

CRUN  GFX2C"CURDNMJ 

QEND 
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LINE    Draw  a  line 


Syntax:      RUN  GFX2([path,]"LINE"[,xcorl,ycorl],xcor2, 
ycor2) 

Function:  Draws  a  line  in  one  of  the  following  ways: 

•  From  the  current  draw  pointer  to  the  specified  X-  and  Y- 
coordinates. 

•  From  the  specified  beginning  X-  and  Y-coordinates  to 
the  specified  ending  X-  and  Y-coordinates, 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

draw  a  line. 

xcorljcorl        The  optional  beginning  X-  and  Y-coordinates 
for  the  line. 

xcor2,ycor2        The  ending  X-  and  Y-coordinates  for  the  line. 
Examples: 

RUN   GFX2C,,LINE",192,128> 
RUN   GFX2<"LINE",0,0,192,128) 

Sample  Program: 

This  procedure  draws  a  sine  wave  of  vertical  lines  across  a 
window. 

PRDCEDURE   waves 

DDIM   A,X,Y,Z: INTEGER 

DCALC=0 

OA-100 

DRUN   GFX2<"CL£AR"> 

DRUN   GFX2<"C0L0RM,3,2J 

DFQR    X-0    TO   638   STEP    1 

DCALC=CALC+.0S 

CY-A-S1N<CALC)*15 

CZ-Y+25 
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DRUN   GFX2("LINEMIX,Y,X,Z> 

QNEXT   X 

□END 


9-104 


Displaying  Thct  and  Graphics  1 9 


LiOCxlO    Perform  logic  function 


Syntax:      RUN  GFX2<"LOGIC'7'/uoctioii") 

Function:  Causes  BASIC09  to  perform  the  specified  logic  func- 
tion on  all  data  bits  used  by  subsequent  drawing  functions. 
Once  set,  the  logic  function  remains  in  effect  until  you  turn 
LOGIC  off. 

Parameters: 

function  can  be  one  of  the  following  logical  functions: 

OFF  —  no  logic 

AND  —  performs  AND  logic 

OR  —  performs  OR  logic 

XOR  —  performs  SDR  logic 

Examples: 

RUN   GFX2<"L0GIC","AND"> 
RUN   GFX2("L0GIC")"X0R") 

Sample  Program: 

This  procedure  uses  LOGIC  to  draw  a  horizontal  bar  across  a 
background  of  multicolored  vertical  bars.  Using  XOR  logic,  the 
procedure  causes  the  horizontal  bar  to  change  the  color  of  each 
vertical  bar. 

PROCEDURE  logic 

DDIM  A, Z,T,X,Y, COLOR: INTEGER 

QRUN  GFX2C"LOGIC,,,"0FF,,J 

URUN  GFX2C"CLEAR") 

DCOLOR*0 

DFOR  T-0  TO  619  STEP  20 

DCDL0R-CDL0R+1 

DRUN  GFX2<"C0LOR,,,COLOR> 

DRUN  GFX2<"BAR,,)T,0)T  +  2e,190> 

DNEXT  T 

DRUN  GFX2<"C0L0R",3,2J 

DRUN  GFX2("L0GIC,\"X0R") 
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DFDR   T-1    TD    10 

DRUN   GFX2<"BAR", 0,80, 639, 112) 

DNEXT    T 

DRUN   GFX2C"LOGIC,,,"0FF") 

QEND 
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(JWfeJirf  1     Establish  an  overlay  window 


Syntax:      RUN  GFX2([patii,]"OWSET",save  switch,xpos, 
ypos,xsize,ysize,foreground,  backgrovm  d) 


Function:  Creates  an  overlay  window  on  a  previously  existing 
device  window.  Reconfigures  the  current  device  window  paths 
to  use  a  new  area  of  the  screen  as  the  current  device  window. 


Parameters: 

path 

save  switch 


xpos 

ypos 

xsize 
ysize 

foreground 
background 


The  route  to  the  window  in  which  you  want  to 
set  an  overlay. 

Either  0  or  1.  A  value  of  0  tells  BASIC09  not 
to  save  the  overlaid  area.  A  value  of  1  tells 
BASIC09  to  save  the  overlaid  area  and  restore 
it  when  the  new  window  closes. 

The  character  column  in  which  to  start  the 
new  window  (upper  left  corner). 

The  character  row  in  which  to  start  the  new 
window  (upper  left  corner). 

The  width  of  the  new  window  in  characters. 

The  depth  of  the  new  window  in  rows. 

The  foreground  color  of  the  new  window, 

The  background  color  of  the  new  window. 


Examples: 

RUN   GFX2<"DWSET,\00,44,10,32,8,00,06> 

Sample  Program: 

This  procedure  creates  six  progressively  smaller  overlay  win- 
dows, labeling  each.  It  then  waits  for  you  to  press  a  key,  after 
which  it  erases  all  the  windows  and  leaves  the  original  window 
intact. 
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PROCEDURE    overwin 

DDIM   X,Y,X1 ,Y1 ,T,J,B,L .PLACE: INTEGER 

DDIM    RESPDNSE:STR1NG[1  ] 

DX-0    \Y  =  B 

DX1-8B    \Y1-24 

DPLACE-33 

DFOR   T-1    TD    6 

DIF   T  =  2    OR   T-6   THEN 

DB*3 

DELSE    B»2 

DENDIF 

DRUN    GFX2("DWSET",1 ,X,Y,X1,Y1,B,T) 

QX-X*6    \Y«Y*2 

DX1-X1-12    W1-Y1-4 

DFOR    J-1    TO   S 

DPRINT   TAB(PLACE);    "Overlay   Screen   " ;    T 

DNEXT    J 

DPLACE-PLACE-6 

DNEXT  T 

DPRINT  "Press  A  Key..."; 

DGET  #1 .RESPONSE 

DFOR  T-1  TO  6 

DRUN   GFX2C0WEND") 

DNEXT   T 

SEND 
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rALihj  1  1  hi    Set  color  for  palette  registers 


Syntax:      RUN  GFX2([path,]"PALETTE",register,color) 


Function:  Sets  palette  colors.  Lets  you  install  any  of  the  Color 
Computer's  64  colors  in  the  palette  for  use  with  text  and 
graphics. 

Parameters: 

path  The  route  to  the  window  where  you  want  to 

change  palette  colors. 

register  The  number  of  the  register  in  which  you  want 

to  install  a  new  color. 

color  The  code  of  the  new  color  you  want  to  install. 

Examples: 

RUN   GFX2<"PALETTE",13,32> 

Sample  Program: 

This  procedure  draws  a  series  of  bars  and  circles,  then  repeat- 
edly changes  their  colors  using  PALETTE. 

PROCEDURE    palette 

DDIM   T, K, J, X,Y, COLOR: INTEGER 

DDIM    RESPDNSE:STRINGM  J 

GRUN   GFX2C"CDL0R,\3,2,2> 

GCOLOR-0 

URUN   GFX2("CLEAR") 

DRUN   GFX2C"CUR0FFM) 

■DFDR    Y-0   TO    23   STEP   3 

DRUM   GFX2C"CDLOR,,,COL0R> 

DRUN   GFX2<"BAR",0,Y,639,Y+3J 

DC0L0R-C0LOR+1 

OIF    C0L0R-2   THEN 

DC0LOR-COLOR*1 

GENDIF 

DNEXT    Y 

DFOR    Y-164    TO    185   STEP   3 
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CRUN   GFX2<"C010R", COLOR) 

CRUN    GFX2("BAR",0,Y,639,Y+3) 

CCOL0R=COLOR+1 

CNEXT    Y 

CCQLOR-0 

[jFOR   K-4S    TO    170    STEP    48 

DFOR   T  =  100    TO   580    STEP    100 

URUN   GFX2C"C0LDR" ,3) 

DRUN   GFX2C"CIRCLE",T,K,30> 

DRUN  GFX2CC0L0R", COLOR) 

DRUN  GFX2C"FILL",T,K) 

DCOlOR=COLOR+1 

DIF    C0L0R=2   THEN 

DCOLOR-COLOR+1 

DENDIF 

CNEXT   T 

DNEXT    K 

DREPEAT 

DX=RNDC63) 

DREPEAT 

DY=RNDC16)*1 

DUNTIL    Y<>2 

DRUN   GFX2("PALETTE",Y,X) 

DRUN  INKEY(RESPONSE) 

DUNTIL   RESPONSE)"" 

GRUN   GFX2«"DEFC0L") 

DRUN    GFX2("CURDN") 

DEND 
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PATTERN    Select  pattern  buffer 


Syntax:      RUN  GFX2([path,]"PATTEKN",group,buffer) 


Function:  Selects  the  contents  of  a  preloaded  Get/Put  buffer  as 
a  pattern  for  graphics  functions.  Although  PATTERN  can  use 
a  buffer  of  any  size,  it  uses  a  specific  number  of  bytes,  depend- 
ing on  the  screen  format  in  use: 

Color  Pattern  Bits 

Mode  Array  Size  Per  Pel 

02  4  bytes  x  8  bytes  =  32  bytes  1 

04  8  bytes  x  8  bytes  =  64  bytes  2 

16  16  bytes  x  8  bytes  =  128  bytes  4 

The  pattern  array  is  a  32  x  8  pel  representation  of  graphics 
memory.  It  takes  the  current  color  mode  into  consideration  to 
define  the  number  of  bits  per  pel  and  pels  per  byte.  If  the 
buffer  is  larger  than  the  number  of  bytes  required,  PATTERN 
ignores  the  extra  bytes.  BASIC09  uses  the  selected  pattern 
with  all  draw  commands  until  you  change  the  pattern  or  turn 
off  the  pattern  function  by  specifying  a  group  and  buffer  num- 
ber of  0. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

use  a  new  graphics  pattern. 

group  The  group  number  of  the  buffer  you  want  to 

use  for  a  graphics  pattern. 

buffer  The  buffer  number  that  you  want  to  use  for  a 

graphics  pattern. 

Examples: 

RUN   GFX2("PATTERN",1  ,3) 
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Sample  Program: 

This  procedure  loads  the  current  window  data  at  location  0,0 
into  a  buffer  to  use  as  a  draw  pattern.  It  then  draws  a  circle  and 
fills  the  circle  with  the  pattern  in  the  buffer. 

PROCEDURE  pattern 

□DIM  X,Y,T:INTECER 

□RUN  GFX2C"GET",1 ,1 ,0,B,5,5> 

□RUN  GFX2C"Cai(3fi*\4) 

□RUN  GFX2("CLEAR"> 

□RUN  GFX2(,,CIRCLE",320,96,100> 

□RUN  GFX2("FILL",320,36> 

DRUM  GFX2CMPATTERN",1 ,1) 

QRUN  GFX2<"CaiOR",3> 

□RUN    GFX2(',F1LL",320,96) 

□RUN    GFX2("PATTERN",0,0) 

□END 
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POINT    Mark  a  point 


Syntax:      RUN  GFX2([patfi,]'TOINT',[,xeor,j«or3) 


Function:  Sets  the  pixel  at  the  current  draw  pointer  position 
or  at  the  specified  coordinates  to  the  current  foreground  color. 
If  you  do  not  specify  coordinates,  POINT  sets  the  pixel  at  the 
draw  pointer. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

turn  on  the  specified  pixels. 

xcor,ycor  Optional  coordinates  for  the  POINT  function. 

The  X-coordinates  are  in  the  range  0-639.  The 
Y-coordinates  are  in  the  range  0-191. 

Examples: 

RUN    GFX2("P0INT") 

RUN   GFX2C,,P0INT", 192,128) 

Sample  Program: 

This  procedure  uses  POINT  to  produce  a  swirl  design  on  a  win- 
dow screen. 

PROCEDURE  point 

DBASE  0 

DDIM  X<20),Y(20):INTEGER 

DDIM   T,R,J,K: INTEGER 

DJ-0 

DK-0 

DRUM   GFX2C"CUR0FF"> 

DRUM   GFX2(,,CLEAR") 

DFDR    T-1     TO    288    STEP    3 

□J  -  J  + 1 

DFDR    R-0    TO    11 

DXCR)-INT(T*SlN<30*R+K)>+320 

DY<R>-INT<J»C0S(3a«R+K>>+96 

DRUN   GFX2<"POINT",X<R),Y<R>> 
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OK-K+1 

DNEXT  R 

CNEXT   T 

DRUM   GFX2("CUR0N"3 

DEND 
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JrxvU  rbW     Proportional  space  switch 


Syntax:      RUN  GFX2([pafh,]"PR0PSW","switeii") 


Function:  Enables  or  disables  the  automatic  proportional  spac- 
ing of  characters  on  graphic  screens. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

use  proportional  character  spacing. 

switch  Either  OFF  to  turn  proportional  spacing  off,  or 

ON  to  turn  proportional  spacing  on.  The 
default  setting  of  the  switch  is  OFF. 

Examples: 

RUN   GFXaCPROPSWVON") 

Sample  Program: 

This  procedure  produces  a  demonstration  of  the  BASIC09  propor- 
tional spacing  function. 

PROCEDURE  proport 

□DIM  LINE:STRING 

□DIM  LETTERiSTRINGCI ] 

□DIM  T, J, K, FLAG: INTEGER 

□RUN  GFX2<MCLEAR") 

DFLAG=1 

LTOR   T=1    TO    12 

CREAD   LINE 

LTOR    J-1    TO   LEN(LINE) 

CLETTER-MID$(LINE, J,1  } 

LIF  LETTERO"!"  AND  LETTER<>"#"  THEN 

CPRINT  LETTER; 

CENDIF 

zif  letter-"!"  then 
:flag»flag*-i 

jIF   FLAG>0    THEN 

"RUN    GFX2("PR0PSW","0FF") 
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DELSE 

DRUN  GFX2C"PR0PSW","0N") 

□ENDIF 

DENDIF 

DIF  LETTER-"*"  THEN 

CPRINT  CHR*<34>; 

DENDIF 

DNEXT  J 

DPR  I  NT 

DNEXT  T 

DPR  I  NT  \  PRINT 

QEND 

DDATA  "This  is  a  demonstration  of" 

DDATA  "(Proportional  Spacing!  using" 

DDATA  "BASIC09's  GFX2  module." 

DDATA  "" 

DDATA  "'The  quick  brown  fox  jumped...!" 

DDATA  "The  quick  brown  fox  Jumped..." 

DDATA  "" 

DDATA  "Use  the  command" 

DDATA  "!RUN  GFX2(#PR0PSW# ,#0N#>!" 

DDATA  "to  turn  proportional  spacing  on," 

DDATA  "Use  "RUN  GFX2C#PR0PSW#,#0FF#) !" 

QDATA  "to  turn  proportional  spacing  off" 
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PUT 


Put  a  saved  data  block  on  the  window 


Syntax:      RUN  GFX2([path,]"PUT\group,buffer, 
xcor,ycor) 


Function:  Places  the  image  in  the  specified  Get/Put  buffer  on 
the  window.  PUT  requires  only  the  group  and  buffer  numbers 
and  the  window  coordinates  for  the  upper  left  corner  of  the 
image.  The  GET  function  saves  the  dimensions  of  the  block  in 
the  buffer.  PUT  automatically  handles  window  format 
conversion. 


Parameters: 

path 

group 
buffer 
xcor,ycor 

Examples: 


The  route  to  the  window  where  you  want  to 
place  a  pre-saved  image. 

The  group  number  of  the  buffer  in  which  to 
save  the  window  data. 

The  buffer  number  in  which  to  save  the  win- 
dow data. 

The  X-  and  Y-coordinates  of  the  upper  left  cor- 
ner of  the  window  position.  The  X-coordinates 
are  in  the  range  0-639.  The  Y-coordinates  are 
in  the  range  0-191. 


RUN    GFX2C"PUT",1 ,5,1 00,50) 
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Sample  Program: 

This  procedure  draws  a  character,  loads  it  into  a  buffer,  then 
repeatedly  replaces  the  character  to  the  window  screen  using 
PUT.  Each  new  image  erases  the  previous  image,  giving  an 
impression  of  animation. 

PROCEDURE  putdown 

DDIM  X,Y,T,J:INTEGER 

DRUN  GFX2("CUR0FF,,> 

DRUM  GFX2<"CLEAR") 

DRUN  GFX2<  "ELL  IPSE",  320,96,1  2,  4) 

CRUN  GFX2<"CIRCLE", 320,90, 5) 

DRUN  GFX2C"C0LOR",1) 

jRUN  GFX2<,,FILL",320,96> 

DRUN  GFX2<"C0L0R",3) 

DRUN  GFX2<"FILL",320,90> 

DRUN  GFX2C"BAR",305,100,3351104) 

DRUN  GFX2C"GET",1 ,1 ,288,85,50,23) 

DRUN  GFX2<"GET",1 ,2,1 ,1 ,50,23) 

DRUN  GFX2(,,PUT",1  ,2,288,85) 

DJ-10 

DFDR  T=20  TO  559  STEP  6 

rj»J+2 

jRUN   GFX2<"PUT",1 ,1 ,T,J) 

DNEXT   T 

DRUN   GFX2("KILLBUFF",1 ,1 ) 

DRUN   GFX2("CUR0N") 

DEND 
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if  U  1  vtO    Put  graphics  cursor 


Syntax:      RUN  GFX2([path,]"P\JTGC",xcor,ycor) 


Function:  Places  and  displays  the  graphics  cursor  at  the  speci- 
fied location.  Use  screen  relative  coordinates  for  this  function, 
not  window  relative  coordinates.  The  horizontal  range  is 
0-639.  The  vertical  range  is  0-191. 

Parameters: 

path  The  route  to  the  window  where  you  want  to 

display  a  graphics  cursor. 

xcor,yeor  The  screen  coordinates  for  the  cursor  location. 

The  X  coordinates  are  in  the  range  0-639.  The 
Y  coordinates  are  in  the  range  0-191. 

Examples: 

RUN   GFX2C"PUTGC",100,5) 

Sample  Program: 

This  procedure  displays  the  available  graphic  cursors  stored  in 
group  202.  Before  this  procedure  can  work,  you  must  merge  the 
Stdptrs  file  in  the  SYS  directory  of  your  system  disk  with  the 
window  you  are  using.  For  instance,  if  your  system  diskette  is  in 
Drive  /DO,  merge  Stdptrs  with  Window  1,  by  typing: 


merge    /d0/sys/5tdpt  rs    >    /wl  I  ENTER  ] 

PROCEDURE  viewcur 

□DIM  T,2:INTE0ER 

DRUN  GFX2CMCLEAR"> 

DFDR  T=1  TD  7 

□RUN  GFX2C,,GCSET",202,T) 

□RUN  GFX2(,,PUTGC,,,320,96) 

□FDR  Z=1  TO  6000 

□NEXT  Z 

□NEXT  T 

□RUN  GFX2("GCSET",0,0> 

GEND 
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RE  VON    Reverse  video  on 
REVOFF    Reverse  video  off 


Syntax:      RUN  GFX2([pa«i,]"REVON") 
RUN  GFX2([patfi,]"REVOFF") 

Function:  Enables  or  disables  reverse  video  characters.  Once 
set,  reverse  video  remains  in  effect  until  you  execute  the 
reverse  video  off  function, 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

display  reverse  characters. 

Examples: 

RUN    GFX2<"REV0N") 
RUN    GFX2("REV0FF") 
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SCALE  SW     Enable/disable  scaling 


Syntax:      RUN  GFX2([path,YlSCALESW>,"awitchn) 


Function:  Enables  or  disables  scaling  when  drawing  on  var- 
iously formatted  windows.  Scaling  in  windows  is  normally  on, 
If  scaling  is  off,  coordinates  are  relative  to  the  window  origin 
coordinates.  Scaling  does  not  affect  text. 

Parameters: 

path  The  route  to  the  window  where  you  want  to 

turn  scaling  off  or  on. 

switch  Either  OFF  (disable  scaling)  or  ON  (enable 

scaling). 

Examples: 

RUN   GFXaC'SCALESW" ,"0FF") 

Sample  Program: 

This  procedure  runs  a  routine  of  drawing  a  design  in  overlay 
windows  twice.  The  routine  runs  once  with  scaling  off  and  once 
with  scaling  on.  After  the  first  routine  pauses,  press  the  space 
bar  to  see  the  second  demonstration. 

PROCEDURE    seals 

GDIM    X,Y,X1,Y1,T,B,J,R,W,Z: INTEGER 

DDIM    RESPONSE:STRINGM 1 

DRUN   GFXSCCLEAR") 

DFOR   J-1    TO   2 

GIF   J-1    THEN 

GRUN   GFX2CMSCALESW","0FF"> 

IELSE 

CRUN   GFX2("SCALESU,,,"0N"> 

DENDIF 

DX-B    \Y-0    \X1-80    \Y1-24 

DFOR   T=1    TO    4 

DIF   T*2    OR   T=G   THEN 

OB-3 


9-121 


BASIC09  Reference 


OELSE    B=2 

OENDIF 

DRUN   GFX2("DWSET",1 ,X,Y,X1 ,Y1 ,B,T) 

DFDR    R-1    TD    35 

DW  =  40»SINCR>H7B 

0Z-25»CQS(R>-<-45 

DRUN   GFX2C"CIRCLE",W,Z,30) 

DNEXT    R 

DX-X+6    \Y=Y*2    \X1-X1-12    W1-Y1-4 

DNEXT   T 

DPRINT  "Press  A  Key. .."; 

DGET   #1 .RESPONSE 

DFDR   T-1    TD   4 

DRUN   GFX2("OWEND"> 

DNEXT    T 

DNEXT    J 

DEND 
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O-Ej  J-iHi  O  X     Select  next  window 


Syntax:      RUN  GFX2([paih],"SELECT") 

Function:  SELECT  causes  a  window  to  display  if  the  proce- 
dure is  operating  in  the  active  window.  If  the  procedure  is  not 
in  the  active  window,  the  newly  selected  window  displays 
when  you  press  I  clear  |.  If  you  do  not  specify  a  path,  BASIC09 
selects  the  device  using  the  standard  input,  standard  output, 
and  standard  error  paths,  Paths  0, 1,  and  2. 

Parameters: 

path  The  path  to  the  window  to  select. 

Examples: 

RUN  GFX2C"SELECT") 
RUN  GFX2C1 ."SELECT") 
RUN  GFX2CPATH, "SELECT") 

Sample  Program: 

From  /TERM,  this  procedure  temporarily  opens  a  path  to 
Window  3,  creates  the  window  format,  and  uses  SELECT  to  dis- 
play the  new  window.  It  draws  a  design,  then  returns  to  the 
/TERM  screen  and  closes  the  path, 

PROCEDURE  design 

DDIM  PATH.T.Y: INTEGER 

DOPEN  *PATH,"/W3":WRITE 

DRUN  GFX2<PATH,"DWSET",5,0,0,80,24,3,2,2> 

CRUN  GFX2CPATH, "SELECT") 

CY-1 

ltor  t«1  to  200  step  3 

:y=y+i 

3?un  gfx2< path, "ell  ipse", 320, 96, t,y) 

GNEXT  T 

GRUN  GFX2<PATH, "COLOR", 1 ,2) 

GFOR  T-200  TO  1  STEP  -6 

CRUN  GFX2« PATH, "ELL IPSE", 320, 96, T,Y) 
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DIF    INT(T/3>-T/3   THEN 

□Y«Y#1 

QENDIF 

DNEXT   T 

QRUN   GFX2«1  ."SELECT") 

DRUN   GFX2CPATH,"DWEND"> 

DCLOSE    #PATH 

DEND 
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SETDPTR    Set  draw  pointer 


Syntax:      RUN  GFX2([pa&,3"SETDPTR",xeor,ycor) 


Function:  Places  the  draw  pointer  at  the  specified  coordinates. 

The  draw  pointer  selects  the  beginning  point  of  the  next 
graphics  draw  function  {such  as  CIRCLE,  LINE,  BOX,  and  so 
on),  if  you  do  not  supply  other  coordinates. 

Parameters: 

path  The  route  to  the  screen  where  you  want  to  set 

the  draw  pointer. 

xcor,ycor  The  screen  coordinates  for  the  draw  pointer 

location.  The  X-coordinates  are  in  the  range 
0-639.  The  Y-coordinates  are  in  the  range  0- 
191. 

Examples: 

RUN   GFX2CMSETDPTR",1  00, 5> 

Sample  Program: 

This  procedure  uses  coordinates  from  a  DATA  statement  for  set- 
ting the  draw  pointer  to  create  a  series  of  star  shapes. 

PROCEDURE  star 

□DIM  X,Y,T,J: INTEGER 

□PRINT  CHR$<12) 

QFDR  J=1  TO  10 

DREAD  X,Y 

□RUN  GFX2("SETDPTR",X+J,Y+J+J> 

DFDR  T-1  TO  5 

DREAD  X,Y 

□RUN   GFX2C"LINE",X+J,Y+J+J> 

DNEXT    T 

DNEXT    J 

DDATA    320,46,440,146,200,84,440,84,200,146,320,46 

DEND 
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UNDLNON    Underline  characters  on 
UNDLNOFF    Underline  characters  off 


Syntax:      RUN  GFX2<[pa*ii,]"UNDLNON") 
RUN  GFX2([pa&,]"UNDLNOFF") 


Function:  Enables  or  disables  character  underline.  After  you 
execute  UNDLNON,  all  characters  displayed  are  underlined 
until  you  execute  UNDLNOFF.  The  default  is  UNDLNOFF. 

Parameters: 

path  The  route  to  the  window  where  you  want  to 

use  underline  characters. 

Examples: 

RUN   OFXa^'UNDLNDN") 

RUN   GFX2("UNDLN0FF") 
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BASIC09  Quick  Reference 


This  chapter  contains  a  quick  reference  of  all  BASIC09  com- 
mands, statements,  and  functions.  It  includes  commands  for  pro- 
gramming, editing,  and  debugging,  as  well  as  the  Commands 
mode  commands. 

The  following  chart  lists  all  BASIC09  keywords  that  you  can  use 

in  a  procedure. 

Statements  and  Functions 


Command 


Description 


ABS 
ACS 
ADDR 

AND 

ASC 

ASN 
ATN 
BASE 

BYE 

CHAIN 

CHD 
CHR$ 

CHX 
CLOSE 

COS 


Returns  the  absolute  value  of  a  number. 

Calculates  the  arccosine  of  a  number. 

Returns  an  integer  value  which  is  the  abso- 
lute memory  address  of  a  variable,  array,  or 
structure  in  a  process's  address  space. 

Generates  the  logical  AND  of  two  Boolean 

values. 

Returns  the  ASCII  code  of  the  first  charac- 
ter in  a  string. 

Calculates  the  arcsine  of  a  number. 

Calculates  the  arctangent  of  a  number. 

Sets  the  lowest  array  or  data  structure  sub- 
script in  a  procedure  to  either  0  or  1. 

Ends  execution  of  a  procedure  and  termi- 
nates BASIC09. 

Executes  a  module,  passing  arguments  if 
appropriate. 

Changes  the  current  data  directory. 

Returns  the  ASCII  character  represented  by 
a  specified  integer. 

Changes  the  current  execution  directory. 

Deallocates  the  specified  path  to  a  file  or 
device. 

Calculates  the  cosine  of  a  number. 
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Command 

Description 

CREATE 

Opens  a  path  and  establishes  a  new  file  on 
disk. 

DATE$ 

Returns  the  computer's  current  date  and 
time. 

DEG 

Causes  BASIC09  to  calculate  angles  in 
degrees. 

DATA 

Stores  data  in  a  procedure  to  be  accessed 
by  the  READ  statement. 

DELETE 

Deletes  a  file  from  disk. 

DEM 

Declares  simple  variables,  arrays  or  complex 
data  structure  for  size  and  type. 

DO 

See  WHILE/DO/ENDWHILE. 

ELSE 

See  IF/THEN/ELSE/ENDIF. 

END 

Terminates  execution  of  a  procedure. 
Returns  to  the  calling  procedure  or  to 
BASIC09's  command  mode.  Displays  the 
specified  text. 

ENDEXTT 

See  EXITIF/ENDEXIT. 

ENDIF 

See  IF/THEN/ELSE/ENDIF. 

ENDLOOP 

See  LOOP/ENDLOOP. 

ENDWHILE 

See  WHILE/DO/ENDWHILE. 

EOF 

Tests  for  the  end  of  a  disk  file. 

ERR 

Returns  the  error  code  of  the  most  recent 

error. 

ERROR 

Generates  the  specified  error. 

EXTTIF/ 
ENDEXIT 

Tests  conditions  in  a  loop.  The  procedure 
exits  the  loop  if  the  condition  is  true. 

EXP 

Calculates  e  (2.71828183)  raised  to  the 
specified  value. 

FALSE 

A  Boolean  function  that  always  returns 
FALSE. 

FEX 

Rounds  a  real  number  and  converts  it  to  an 
integer. 

FLOAT 

Converts  a  byte  or  integer  value  to  a  real 
number. 
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Command 


Description 


FOR/NEXT 

GET 

GOSUB/ 
RETURN 

IF/THEN/ELSE/ 
ENDIF 


INKEY 

INPUT 

INT 

KILL 

LAND 

LEFT$ 

LEN 
LET 
LNOT 

LOG 

LOG10 

LOOP/ 
ENDLOOP 

LOR 


Creates  a  program  loop  of  a  specified  num- 
ber of  repetitions. 

Reads  an  element  or  a  data  structure  from 
a  binary  file  or  a  device. 

Transfers  program  control  to  a  specified 
subroutine.  RETURN  sends  execution  back 
to  the  calling  routine. 

Evaluates  an  expression  and  performs  an 
operation  if  the  conditions  are  met.  Includ- 
ing ELSE  causes  an  alternate  operation  if 
the  conditions  are  false. 

Stores  the  character  of  a  keypress  in  a 
string  variable. 

Causes  a  procedure  to  accept  input  from 
the  keyboard  or  other  specified  device. 

Returns  the  largest  whole  number  less  than 
or  equal  to  the  specified  value. 

Unlinks  a  procedure.  (Removes  it  from 
BASIC09's  directory.) 

Performs  a  bit-by-bit  logical  AND  on 

two-byte,  or  integer,  values. 

Returns  the  specified  number  of  characters, 
from  the  leftmost  portion  of  a  string. 

Returns  the  length  of  the  specified  string. 

Assigns  a  value  to  a  variable. 

Performs  a  bit-by-bit  logical  NOT  function 
on  two-byte,  or  integer,  values. 

Calculates  the  natural  logarithm. 

Calculates  a  base  10  logarithm. 

Establishes  a  loop.  Use  EXITIF  and 
ENDEXIT  to  test  the  loop  and  exit  when  a 
specified  condition  is  true. 

Performs  a  bit-by-bit  logical  OR  on  two- 
byte,  or  integer,  values. 
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Command 


Description 


LXOR 
MID$ 

MOD 

NEXT 
NOT 

ON  ERROR/ 
GOTO 

ON/GOSUB 


ON/GOTO 

OPEN 

OR 

PARAM 

PAUSE 

PEEK 

PI 
POKE 

POS 


Performs  a  bit-by-bit  logical  EXCLUSIVE 
OR  on  two-byte,  or  integer,  values. 

Returns  the  specified  number  of  characters, 
beginning  at  the  specified  position  in  a 
string. 

Returns  the  modulus  (remainder)  of  a  divi- 
sion operation. 

See  FOR/NEXT. 

Returns  the  logical  complement  of  a  Boolean 
value. 

Traps  errors  and  transfers  control  to  the 
specified  line  number. 

Evaluates  an  expression.  Then,  selects  from 
a  list  the  line  number  that  is  in  the  posi- 
tion indicated  by  the  result  of  the  expres- 
sion. Procedure  execution  transfers  to  the 
selected  line. 

Evaluates  an  expression.  Then,  selects  from 
a  list  the  line  number  that  is  in  the  posi- 
tion indicated  by  the  result  of  the  expres- 
sion. Procedure  execute  jumps  to  the 
selected  line. 

Opens  an  I/O  path  to  an  existing  file  or 
device. 

Performs  a  logical  OR  on  two  Boolean 
values. 

Describes  the  parameters  a  called  proce- 
dure expects  from  a  calling  procedure. 

Suspends  execution  of  a  procedure,  and 
enters  the  Debug  mode. 

Returns  the  byte  value  of  a  memory 

address. 

Represents  the  constant  3.14159265. 

Stores  a  byte  value  at  a  specified  memory 
address. 

Returns  the  current  character  position  of 
the  print  buffer. 
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Command 


Description 


PRINT 

PRINT  USING 

PRINT# 

PRINT#  USING 

PUT 
RAD 

READ 

REM 

REPEAT/UNTIL 

RESTORE 

RETURN 
RIGHT$ 

RND 

RUN 

SEEK 

SGN 

SHELL 

SIN 
SIZE 

SQ 


Sends  the  specified  characters  or  values  to 
the  display. 

Sends  characters  or  values  to  the  display, 
using  the  specified  format. 

Send9  the  specified  characters  or  values  to 
the  specified  path. 

Sends  characters  or  values  to  the  specified 
path  using  the  specified  format. 

Writes  data  to  a  random  access  file. 

Causes  BASIC09  to  calculate  angles  in 
radians. 

Accesses  data  from  procedure  DATA  lines  or 

from  files  or  devices. 

Indicates  that  the  following  characters  in  a 
procedure  line  are  comments  and  are  not  to 
be  executed.  Also  use  (*  *),  or  (*. 

Establishes  a  loop  that  executes  until  the 
specified  condition  is  met. 

Restores  the  DATA  pointer  to  the  first  data 
item  or  to  a  specified  line. 

See  GOSUB/RETURN. 

Returns  the  number  of  characters  specified, 
from  the  rightmost  portion  of  a  string. 

Returns  a  random  number  from  a  specified 
range. 

Calls  another  procedure  for  execution. 

Changes  the  file  pointer  address. 

Determines  the  sign  of  a  number. 

Calls  an  OS-9  command  or  program  for 
execution. 

Calculates  the  sine  of  a  specified  value. 

Returns  the  number  of  bytes  assigned  to  a 
variable,  array,  or  complex  data  structure. 

Calculates  a  value  raised  to  the  power  of 
two. 
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Command 

Description 

SQR/SQRT 

Calculates  the  square  root  of  a  positive 
number, 

STEP 

Sets  the  size  of  increment  in  a  FOR/NEXT 
loop. 

STOP 

Terminates  the  execution  of  all  procedures 
and  returns  to  the  BASIC09  Command 

mode. 

STR$ 

Converts  numeric  data  to  string  data. 

SUBSTRING 

Returns  the  starting  position  of  a  sequence 
of  characters  in  a  string. 

SYSCALL 

Executes  an  OS-9  System  Call. 

TAB 

Begins  a  print  operation  at  the  specified 
column. 

TAN 

Calculates  the  tangent  of  a  value. 

TRIM$ 

Strips  trailing  spaces  from  the  specified 
string. 

TRON/TROFF 

Turn  the  trace  mode  on  and  off. 

TRUE 

Returns  the  Boolean  value  of  TRUE, 

TYPE 

Defines  a  new  data  type. 

UNTIL 

See  REPEAT/UNTIL. 

USING 

See  PRINT  USING. 

VAL 

Converts  a  string  to  an  integer. 

WHILE/DO/ 
ENDWHILE 

Executes  a  loop  as  long  as  a  specified  condi- 
tion is  true. 

WRITE 

Writes  data  in  ASCII  format  to  a  file  or 
device. 

XOR 


Performs  a  logical  EXCLUSIVE  OR  on  two 
Boolean  values, 
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Commands  by  Type 

Statements 

BASE  0       DIM                      GOSUB 

OPEN 

RETURN 

BASE  1        ELSE                    GOTO 

PARAM 

RUN 

BYE            END                     IF/THEN 

PAUSE 

SEEK 

CHAIN        ENDEXIT            INPUT 

POKE 

SHELL 

CHD            ENDIF                  KILL 

PRINT 

STOP 

CHX            ENDLOOP           LET 

PUT 

TROFF 

CLOSE        ENDWHILE         LOOP 

RAD 

TRON 

CREATE     ERROR                NEXT 

READ 

TYPE 

DATA           EXITUVTHEN     ON  ERROR/GOTO 

REM 

UNTIL 

DEG            FOR/TO/STEP      ON/GOSUB 

REPEAT 

WHILE/DO 

DELETE     GET                     ON/GOTO 

RESTORE 

WRITE 

Transcendental  Functions 

ACS                 COS 

LOG10 

SIN 

ASN                EXP 

PI 

TAN 

ATN                LOG 

Numeric  Functions 

ABS                LAND 

MOD 

SQ 

FIX                 LNOT 

RND 

SQR 

FLOAT            LOR 

SGN 

SQRT 

INT                 LXOR 

String  Functions 

ASC                 LEFT$ 

RIGHT$ 

TRIM$ 

CHR$              LEN 

STR$ 

VAL 

DATE$             MIDI 

SUB 

STR 

INKEY 

Miscellaneous  Functions 

ADDR             FALSE 

SIZE 

SYSCALL 

EOF                PEEK 

TAB 

ERR                POS 

TRUE 
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Data  Types 

The  following  list  shows  the  BASIC09  data  type  you  can  specify 
when  defining  a  variable. 


Type 


Function 


BOOLEAN  Returns  TRUE  or  FALSE 

BYTE  Specifies  that  a  numeric  variable  is  to  store 

single-byte  values, 

INTEGER  Specifies  that  a  numeric  variable  is  to  store 

integer  (two-byte)  values. 

REAL  Specifies  that  a  numeric  variable  is  to  store 

real  (five-byte)  values. 

STRING  Specifies  that  a  variable  is  to  store  ASCII 

characters. 


Types  of  Access  for  Files 

%u  can  use  the  following  parameters  with  the  CREATE  and 
OPEN  commands.  Check  the  individual  commands  for  informa- 
tion on  which  parameter  to  use  with  which  command. 


Parameter 


Function 


DIR 

EXEC 

READ 

WRITE 

UPDATE 


Lets  BASIC09  access  a  directory-type  file 
for  reading.  Do  not  use  with  UPDATE  or 
WRITE. 

Lets  BASIC09  access  the  current  execution 
directory  rather  than  the  current  data 
directory. 

Sets  the  file  access  mode  for  reading. 

Sets  the  file  access  mode  for  writing. 

Sets  the  file  access  mode  for  both  reading 
and  writing. 
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Command  Mode 

The  following  chart  lists  the  commands  available  from  the 
BASIC09  Commands  mode: 


Command 


Function 


$ 

BYE  or 

CHD 
CHX 
DIR 


EDIT  or  E 
KILL 

LIST 

LOAD 

MEM 

PACK 

RENAME 
RUN 

SAVE 


Calls  the  shell  command  interpreter  to  exe- 
cute an  OS-9  command. 

Returns  you  to  the  OS-9  system  or  to  the 
program  that  called  BASIC09. 

Changes  the  current  data  directory. 

Changes  the  current  execution  directory. 

Displays  the  name,  size,  and  variable  stor- 
age requirement  of  each  procedure  in  the 
workspace. 

Enters  the  procedure  editor/compiler  mode. 

Removes  one  or  more  procedures  from  the 
workspace. 

Displays  a  formatted  listing  of  one  or  more 
procedures. 

Loads  all  procedures  from  a  file  into  the 
workspace. 

Displays  current  workspace  size  or  reserves 
a  specified  amount  of  memory  for  the 
workspace. 

Performs  a  second  compilation  and  stores 
the  resulting  file  in  the  execution  directory. 

Changes  a  procedure's  name. 

Causes  a  procedure  to  execute. 

Writes  one  or  more  procedures  to  disk. 
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Edit  Commands 

The  following  chart  lists  the  commands  available  from  the  Edit 
mode: 


Command 


Function 


[ENTER  | 
+  num 

+  * 

—  minx 


_* 
text 

line 


/iaeflNTERl 

cistrl/str2/ 

c*Istrl/str2 

d 

d* 

1 

1* 

q 

r 


r  line 

r  line  aum 


Blstr 
B*fstr 


Moves  the  edit  pointer  to  the  next  line. 

Moves  the  edit  pointer  forward  a  specified 
number  of  lines. 

Moves  the  edit  pointer  past  the  last  line. 

Moves  the  edit  pointer  back  a  specified 
number  of  lines. 

Moves  the  edit  pointer  to  the  first  line. 

A  space  followed  by  text  inserts  an  unnum- 
bered line  before  the  current  line. 

Typing  a  line  number  with  or  without  text 
following  it  inserts  the  line  into  the 
procedure. 

Moves  the  edit  pointer  to  the  line  line. 

Changes  the  text  strl  to  the  text  str2. 

Changes  all  occurrences  of  strl  to  str2. 

Deletes  the  current  line. 

Deletes  all  the  lines  in  the  procedure. 

Lists  the  current  line. 

Lists  all  the  lines  in  the  current  procedure. 

Terminates  the  edit  session. 

Renumbers  lines  from  the  first  line  number, 
in  increments  of  10. 

Renumbers  all  numbered  lines  in  incre- 
ments of  10.  The  first  line  number  is  100. 

Renumbers  lines  from  line  in  increments  of 
10. 

Renumbers  lines  from  line,  in  increments  of 
num. 

Searches  for  the  first  occurrences  of  str. 

Searches  for  all  occurrences  of  str. 
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Debug  Commands 

The  following  table  lists  all  the  Debug  commands  and  what  they 
accomplish: 


Command 


Function 


^command 

BREAK 

CONT 
DEG/RAD 

DIR 
Q 

LET 

LIST 

PRINT  var 
STATE 

STEPnum 

TRON/TROFF 


Tells  BASIC09  to  execute  the  specified  OS-9 
command  or  program. 

Sets    a    breakpoint    at    the    specified 

procedure. 

Causes  procedure  execution  to  continue. 

Selects  either  degrees  or  radians  as  the  unit 
of  angle  measurement  for  trigonometric 
functions. 

Displays  the  procedures  in  the  workspace. 

Leaves  the  Debug  mode  for  the  System 
mode. 

Assigns  a  new  value  to  a  variable. 

Displays  a  source  listing  of  the  suspended 
procedure. 

Displays  the  value  of  the  specified  variable. 

Lists  the  nesting  order  of  all  active 
procedures. 

Causes  execution  of  the  suspended  proce- 
dure in  specified  increments. 

Turns  the  trace  function  on  and  off. 
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BASIC09  Command  Reference 


BASIC09  is  made  of  keywords  (functions  and  statements)  that 
you  use,  with  their  parameters,  to  instruct  the  computer  to  per- 
form certain  operations. 

This  chapter  is  a  complete  reference  for  all  of  BASIC09's 

keywords. 

Keyword  Format 

The  reference  to  each  keyword  is  organized  in  this  manner: 

•  The  keyword, 

•  The  proper  syntax  (spelling  and  form)  for  using  the 
keyword, 

•  A  brief  description  of  the  keyword's  purpose  or  effect. 

•  Descriptions  of  any  parameters  or  arguments  for  the 
keyword, 

•  Notes  about  special  features  or  requirements  of  the  key- 
word, when  appropriate. 

•  One  or  more  examples  for  using  the  keyword. 

•  One  or  more  sample  procedures. 

This  format  can  vary  slightly,  depending  on  the  complexity  of 
each  keyword.  For  instance,  some  keywords  require  parameters 
or  arguments,  and  others  do  not.  Some  keywords  are  self- 
explanatory  and  do  not  require  a  sample  procedure. 

The  Syntax  Line 

The  second  line  in  each  command  or  keyword  reference  is  the 
syntax  line.  This  line  uses  keyword  constants  and  keyword  vari- 
ables to  show  you  how  to  construct  a  command  line.  Constants 
are  words,  numbers,  or  symbols  that  you  type  exactly  as  they 
appear.  Variables  are  words  that  only  represent  the  actual 
words,  numbers,  or  symbols  that  you  must  supply  for  the 
command. 
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All  variables  are  italic.  When  you  see  an  italicized  word,  you 
know  that  you  must  supply  some  other  word,  name,  symbol,  or 
value  in  place  of  that  word.  If  a  word,  symbol,  or  value  is  not 
italicized,  type  it  exactly  the  way  it  appears  in  the  syntax  line. 

The  syntax  line  also  uses  symbols  to  help  you  understand  how  to 
construct  a  command  line.  These  symbols  are: 

[  ]  Words,  names,  value,  or  symbols  contained  between 
right  and  left  brackets  are  optional.  You  can  use  them 
or  not,  depending  on  what  you  want  to  accomplish  with 
the  command. 

. . .  Ellipsis  indicates  that  the  last  parameter  can  be 
repeated. 

The  following  syntax  line  for  DELETE  requires  only  one  param- 
eter, the  variable  pathname. 

DELETE  "pathname" 

Because  pathname  is  italicized,  you  know  that  you  must  replace 
it  with  other  text — in  this  case  the  pathlist  to  the  file  you  want 
to  delete.  If  you  wanted  to  delete  a  file  named  Test  from  the 
ROOT  directory  of  Drive  /Dl,  this  syntax  line  tells  you  that  you 
must  type: 

delete  "/dl/test" 

Other  syntax  lines  are  more  complex,  such  as  the  line  for 
CREATE: 

CREATE    #path, "pathlist"    [access   model 

l+access   model C* .. .] 

This  line  tells  you  how  to  create  a  path  to  a  file  or  device. 
Because  the  number  symbol  (#)  is  not  italicized,  you  type  it 
after  the  blank  space  following  the  keyword.  However, 
path, pathlist,  and  access  mode  are  all  italicized.  You  must 
replace  them  with  other  names  or  values. 

The  access  mode  variable  is  contained  within  brackets.  This  tells 
you  that  it  is  optional.  You  can  include  an  access  mode,  or  not.  If 
you  don't,  BASIC09  opens  the  path  in  the  Update  Mode. 

The  second  access  mode  shows  that  the  command  allows  two 
access  mode  parameters,  preceded  by  a  plus  symbol.  The  ellipsis 
show  that  you  can  have  even  more  access  mode  parameters. 
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Other  syntax  lines  show  that  no  parameters  are  required,  such 
as: 

DATE* 

This  command  returns  the  current  date.  There  is  nothing  it 
requires,  and  you  can  do  nothing  else  with  it. 

Sample  Programs 

The  sample  programs  in  this  chapter  are  complete.  That  is,  you 
can  type  them,  run  them,  and  get  a  result.  The  procedures  let 
you  see  the  syntax  and  form  of  a  command,  as  well  as  showing 
you  how  it  might  be  used  in  a  program. 

Because  the  programs  are  executable,  the  manual  shows  unfor- 
matted listings  (without  relative  address,  indented  control  struc- 
tures, and  so  on}.  This  helps  eliminate  confusion  for  you  when 
you  type  the  program.  "You  can  type  it  exactly  as  it  appears,  exit 
the  editor,  and  run  the  procedure. 
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AIjO    Return  absolute  value 


Syntax:      ABSinumber) 

Function:  Computes  the  absolute  value  of  number,  A  number's 
absolute  value  is  its  magnitude  without  regard  to  its  sign. 
Absolute  values  are  always  positive  or  zero. 

Parameters: 

number  Any  positive  or  negative  number. 

Examples: 

PRINT  ABS<-GG> 
X«ABSm 

Sample  Program: 

The  following  procedure  asks  you  to  type  the  temperature,  and 
makes  an  appropriate  comment.  It  uses  ABS  to  get  the  absolute 
value  of  the  temperature. 

PROCEDURE  temperature 

HD1M  TEMP: INTEGER 

HINPUT  "What's  the  temperature  outside?  (Degrees 

F). . .",TEMP 

IIF  TEMP<0  THEN 

CPRINT  "That's  ";  ABS(TEMP);  "  below 

zero! dDB  rrrrrrri" 

DEND 

QENDIF 

HIF  TEMP-0  THEN 

UPRINT  "Zero  degrees?  That's  mighty  cold!" 

ZEND 

CENDIF 

DPRINT  TEMP;  "  degrees  above  zero?  That's  kind  of 

bo lmy ..." 

DEND 
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ACS 


Return  arccosine 


Syntax:      ACS(number) 

Function:  Calculates  the  arccosine  of  number.  Use  the  DEG  or 
RAD  commands  to  tell  BASIC09  if  number  is  in  degrees  or 
radians.  If  you  do  not  specify  degrees  or  radians,  the  default 
is  radians. 

Parameters: 

number  The  number  for  which  you  want  to  compute 

the  arccosine. 

Examples: 

PRINT   ASC(.6561 ) 

Sample  Program: 

The  procedure  calculates  the  arccosine  of  a  value  you  type  and 
expresses  the  result  in  degrees. 

PROCEDURE  arccosine 

DDEG 

CDIM    NUM:REAL 

HINPUT   "Enter    a    number    between    -1    and    1",NUM 

GPRINT      "The     arccosine      of      "j      NUM;      "      is "j 

ACS(NUM) 
DEND 


11-5 


BASIC09  Reference 


ALJljix    Return  the  location  of  a  variable 


Syntax:      ADDRtnaroe) 


Function:  Returns  the  absolute  location  in  a  process's  address 
space  of  the  variable,  array,  or  data  structure  assigned  to 
name.  The  address  returned  is  that  of  the  first  character  in 
the  variable.  If  the  variable  is  numeric,  one  or  more  of  the 
locations  might  contain  zero. 

For  instance,  if  you  use  ADDR  to  obtain  the  address  of  an 
integer  variable  that  contains  the  value  44,  the  first  address 
location  (byte)  contains  0,  and  the  second  location  contains  44. 

Parameters: 

name  The  name  of  a  string,  a  numeric  variable,  an 

array,  or  a  data  structure. 

Examples: 

This  procedure  displays  the  memory  address  where  a  variable 
named  X  resides: 

PRINT  ADDRCX) 
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Sample  Program: 

This  procedure  uses  ADDR  to  tell  you  the  memory  location  of 
the  variable  that  stores  your  keyboard  entry, 

PROCEDURE  address 

DDIM  A: INTEGER 

DDIM  TEST:STRING 

CINPUT  "Type  a  string  of  character s ..." .TEST 

CA=ADDRCTEST) 

CPRINT  "The  string  you  typed  Is  stored  at  address 

";  A 

DPRINT  "This  is  what  it  contain " 

CFOR  T-A  TO  A+LENtTEST) 

CPRINT  CHR$CPEEK(T>>; 

CNEXT  T 

CPRINT 

CEN0 
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AJN  \J    Performs  a  logical  AND  operation 

Syntax:       operandi  AND  operand2 

Function:  Performs  the  logical  AND  operation  on  two  or  more 
values,  returning  a  value  of  either  TRUE  or  FALSE. 

Parameters: 

operandi  Can  be  either  numeric  or  string  values, 

operand2 

Examples: 

PRINT  A>3  AND  B>3 

PRINT  A$="YES"  AND  B$="YE5" 

Sample  Program:  /"*v 

The  following  program  calculates  an  insurance  premium  rate 
that  is  based  on  the  answers  to  some  lifestyle  questions.  Every 
time  you  press  (T),  the  premium  rate  goes  up.  The  procedure 
uses  AND  to  increase  the  rate  by  two  percent  if  you  both  smoke 
and  drink. 

PROCEDURE    policy 

IDIM   POLICY—VALUE, RATE: REAL 

HDIM   SMOKE, DRINK:STRINGM  ] 

GP0LICY_VALUE=1  000000 . 

DRATE=.001 

DINPUT  "Do  you  smoke?  < Y/N) ...", SMOKE 

DINPUT  "Do  you  drink?  < Y/N) ... ".DRINK 

DIF  SM0KE-"Y"  AND  DRINK-"Y"  THEN  RATE*RATE+ . 02 

DELSE 

DIF  SM0KE="Y"  THEN  RATE=RATE+ . 01 

DENDIF 

DIF  DRINK-"Y"  THEN  RATE-RATE+ . 01  ^^ 

DENDIF 

DENDIF 

DPRINT  "Your  premium  is  ";  RATE*P0L I CY_VALUE 

DEND 
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ASC    Returns  ASCII  code 


Syntax:      ASC(string) 

Function:  Returns  the  ASCII  code  for  the  first  character  of 
string. 

ASC  returns  the  value  as  a  decimal  number.  If  string  is  null 
(contains  no  characters)  BASIC09  returns  Error  67  (Illegal 
Argument). 

Parameters: 

string  Any  string  type  variable  or  constant. 

Examples: 

PRINT  ASC<"Hello"> 
X  -  ASC<A$> 

Sample  Program: 

The  following  procedure  determines  whether  the  first  character 
you  enter  is  a  hexadecimal  digit.  To  do  this,  it  gets  the  ASCII 
value  of  the  character  and  compares  it  to  the  ranges  for  charac- 
ters between  1  and  0  and  A  and  F. 

PROCEDURE   hexchecle 

□DIM   A: INTEGER 

DDIM    HEXNUM:STRING 

DLOOP 

GINPUT  "Enter  a  hexadecimal  value ...", HEXNUM 

DA-ASC<HEXNUM)  \  («  GET  THE  ASCII  CODE  *> 

DEXITIF  A<48  OR  A>57  AND  A<6S  OR  A>70  THEN 

DPRINT  "Not  a  hex  number." 

DEND 

OENDEXIT 

CPRINT  "Dk." 

OENDLODP 

DEND 
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ASN    Returns 


arcsine 


Syntax:      ASN(jmmber) 


Function:  Calculates  the  arcsine  of  number.  ASN  expresses  its 
result  in  radians  unless  you  specify  otherwise  (see  DEG). 

Parameters: 

number  The  number  for  which  you  want  to  calculate 

the  arcsine. 

Examples: 

PRINT   ASCC.6S61 ) 

Sample  Program: 

The  following  program  calculates  the  arcsine  of  a  number  you 
enter  and  expresses  the  result  in  degrees. 

PROCEDURE  arcsine 

DDIM  NUMiREAL 

□DEG 

□INPUT   "Enter    a    number    C-1    to    1)    ",NUM 

□PRINT     "The     arcsine     of     a     " ;      NUM;      "      is "-, 

ASN(NUM) 
CEND 
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A.1  JN     Returns  arctangent 


Syntax:      ATN(numder) 

Function:  Calculates  the  arctangent  of  number. 

Parameters: 

number  The  number  for  which  you  want  to  find  the 

arctangent. 

Examples: 

PRINT  ASCC.6561 ) 

Sample  Program: 

This  procedure  calculates  arcsine,  arccosine,  and  arctangent  for 
a  value  you  enter, 

PROCEDURE  anglecalc 

DDIM  NUM:REAL 

DDEG 

DINPUT  "Enter  a    number  ",NUM 

DPRINT 

DPRINT  "  "."Arcaine", "Arccosine", "Arctangent" 

DPRINT  "Number ","Degreea","Degree5" ."Begreea" 

CPRINT" 


CIF    NUM>1     OR    NUM<-1    THEN 

3PRI NT   NUM , "UNDEF" , "UNDEF" , ATN<NUM> 

DPRINT 

3END 

DENDIF 

DPRINT   NUM,ASN<NUM),ACSCNUM),ATN(NUMJ 

DPRINT 

DEND 
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-KAo-Cj     Set  array  base 


Syntax:      BASE  0 
BASE  1 


Function:  Sets  a  procedure's  lowest  array  or  data  structure 
index  to  either  0  or  1.  If  you  want  to  have  the  first  elements  in 
arrays  set  to  0,  you  must  include  BASE  0  at  the  beginning  of 
the  procedure. 

The  BASE  statement  does  not  affect  string  operations  such  as 
MID$,  RIGHTS,  and  LEFT$.  BASIC09  always  indexes  the 
first  character  of  a  string  as  1. 

Parameters: 

0  or  1  If  you  do  not  indicate  a  BASE  setting  in  a  pro- 

cedure, BASIC09  uses  a  default  of  1. 

Examples: 

BASE     0 

Sample  Program: 

This  procedure  determines  how  many  times  RND  selects  each 
number  between  0  and  11  out  of  1000  selections.  It  stores  the 
results  in  an  array  of  12  elements.  Because  it  specifies  BASE  0, 
one  of  the  elements  in  the  array  is  0.  Whenever  the  procedure 
picks  a  random  number,  it  increments  the  value  in  the  corre- 
sponding array  number  by  one. 

PROCEDURE  randomtest 

DBASE  i  (>  set  the  array  base  at  I. 

HDIM  RND — ARRflY (1 2), I,R: INTEGER  (»  dimension  array  to  hold  results. 


0FDR  I-l  TO  11 

D?ND_ARRftYU)-B 

(«  initialize  array  elements  at  zero. 

DOT  X 

DSHELL  "TMODE  -PAUSE" 

{•  turn  off  screen  pause. 

DFDR  M  TO  Itfl 

DR-RND(H) 

(»  select  random  number  1111  limes. 

11-12 


BASIC09  Command  Reference  1 11 


DRND fiRRftVCR}- RND ARRAY CRJ+T 

(*  add  1  to  appropriate  element. 

DPRINT  1111-11  (t  count  down  from  I  HI  to  1. 

DOT  X 

HFDR  X-8  TD  11 

DPRINT  "RNO  selected  ";  X;  "  ";  RND flRRfly(X);  " 

times."  ('display  array 

ONE  XT  X 

DSHELL  "TMODE  PAUSE"  (.  turn  scroll  lock  bad  on. 

KND 
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O  YE    End  procedure,  terminate  BASIC09 

Syntax:      BYE 

Function:  Ends  execution  of  a  procedure  and  terminates 
BASIC09.  The  statement  closes  any  open  files,  but  you  lose 
any  unsaved  procedures  or  data. 

Use  BYE  to  exit  packed  programs  that  you  call  from  OS-9  and 
especially  programs  that  you  call  from  procedure  files. 

Parameters:  None 
Examples: 

INPUT  "Press  ENTER  to  return  to  the  system. ";Z$ 
BYE 

Sample  Program: 

This  procedure  calculates  the  payments  and  interest  of  a  loan. 
When  it  is  through,  it  exits  the  procedure  and  BASIC09  with  a 

BYE  statement. 

PROCEDURE  loan 

DDIM  PR1N,LENO.,RATE,MONPAY:REAL 

DD!M  RESPQNSE:STR1NGM] 

DREPEAT 

SPRINT  "Amorti2ation  Program" 

GINPUT  "How  much  do  you  want  to  borrow?. ..", PR  IN 

DINPUT  "For  how  many  months?. . .",LEN0 

DINPUT  "At  what  interest  rate?. . .".RATE 

DA'RATE/12M  . 

DB=1-1/(1tA)"LEN6 

rj1QNPfiY-PRFN»A/B 

CMDNPAY=lNT(MONPAY»198t.5)/1fl8 

GPRIHT  "Monthly  payments  are...$"; 

DPR  I  NT  USING  "R12.2<",I10NPAY 

QPRINT  "The  total  interest  to  pay  is...$"; 

QPRINT  USING  "r12.2<",M0NPAY»LENG-PR]N 

DPR  INT 

DINPUT  "Do  another  calculation?. ..".RESPONSE 

DPR  I  NT 

QPRINT 

□UNTIL  RESPONSEO'T' 

ZIBYE 

DEND 
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C'-H.  A1JN     Execute  another  module 


Syntax:       CHAIN  "module  [parameters}[...]" 


Function:  CHAIN  performs  an  OS-9  chain  operation,  passing 
module  as  the  name  of  a  program  to  execute.  If  you  include 
other  parameters,  CHAIN  passes  them  to  the  executing  mod- 
ule. The  module  must  be  programmed  to  expect  parameters  of 

the  type  you  provide. 

CHAIN  exits  BASIC09,  unlinks  BASIC09,  and  returns  the 
freed  memory  to  OS-9. 

CHAIN  can  begin  execution  of  any  module,  not  only  BASIC09 
modules.  It  executes  the  module  indirectly  through  the  shell 
in  order  to  take  advantage  of  the  shell's  parameter  processing. 
This  has  the  side  effect  of  leaving  the  initiated  shells  active. 
Programs  that  repeatedly  chain  to  each  other  eventually  fill 
memory  with  waiting  shells.  To  prevent  this,  use  the  EX 
option  to  initialize  a  shell. 

BASIC09  does  not  close  files  that  are  open  when  you  execute 
CHAIN.  However,  the  OS-9  FORK  call  passes  only  the  stan- 
dard I/O  paths  (0,  1,  and  2)  to  a  child  process.  Therefore,  if 
you  need  to  pass  an  open  path  to  another  program  segment, 
use  the  EX  shell  option. 

Parameters: 

module  The  name  of  the  procedure  module  you  want 

BASIC09  to  execute. 

parameters        String  data  passed  to  the  chained  module. 
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Examples: 

CHAIN  "ex  BASIC09  menu" 

CHAIN  "BASIC09  #1 0k  sort  C""dataf i le"" , 
""tempf lie"")" 

CHAIN  "DIR  /D0" 

CHAIN  "Dir;  Echo  **«  Copying  Directory  ***;  ex 
basic09  copydir" 

Sample  Program: 

This  procedure  chains  to  two  others  to  display  a  directory  or  a 
file.  It  uses  CHAIN  to  call  the  procedures. 

PROCEDURE  chaining 

DDIM  RESPDNSEiBYTE 

DPRINT  USING  "S26"","-  MENU  -"  <«  print  menu  title. 

DPR  I  NT 

DPRINT  "1.  List  current  data  directory"  (»  print  menu. 

DPRINT  "2.  Display  a  file" 

DPRINT  "3.  Exit  to  system" 

DPRINT 

QINPUT  "Select  a  function  (1-3)  ".RESPONSE  (•  function  you  want. 

DON  RESPONSE  GOTO  100,200,300  (»  select  appropriate  function. 

leeOCHAIN  "EX  BASIC09  dirlook"  (•  chain  to  list  directory. 

200GCHAIN  "EX  BASIC09  display"  (»  chain  to  list  file. 

30OYE 

PROCEDURE  dirlook 

DREM  Lists  the  specified  directory 

■DSHELL  "DIR"       (»  execute  dir  command. 

jCHAIN  "EX  BAS1C09  chaining"  (*  chain  back  to  calling  proc. 

CEND 

PROCEDURE  display 

DREM  Lists  the  specified  file. 

DDIM   FILE.JOBiSTRINO 

DINPUT  "Path  of  file  to  display. ..", FILE 

CJOB'TIST  "♦FILE 

DSHELL  JOB  (*   list  specified  file. 

DCHAIN  "EX  BASIC09  chaining"  (•  chain  back  to  calling  proc. 

DEND 
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O-HJJ    Change  data  directory 
(_>rlX    Change  execution  directory 


Syntax:      CHD  dirpath 
CHX  dirpath 

Function:  Changes  the  current  data  or  execution  directory. 

Parameters: 

dirpath  An  existing  data  or  execution  directory. 

Examples: 

CHD  'VD1 /ACCOUNTS/RECEIVABLE" 

CHX  "/D1/CMDS" 

CHD 

Sample  Program: 

This  procedure  creates  a  directory,  and  makes  it  the  data  direc- 
tory. Then,  it  creates  a  file  in  the  new  directory,  exits  the  new 
directory,  and  deletes  the  file  and  the  directory. 

PROCEDURE  chdteat 

L~DIM  PATH: BYTE 

DSHELL  "MAKDIR  TEST"  (»  create  new  directory  named  TEST. 

DCHD  "TEST"  ('  make  TEST  the  data  directory. 

DCREATE  *P ATH, "samp lefile": WRITE  (•  create  a  file  in  TEST. 

DREM  Write  data  into  the  new  file 

DWRITE  *PATH,"This  file  is  for  testing  only." 

JIRITE  'PATH, "It  will  be  destroyed  when  this  procedure  ends." 

HCLDSE  #PATH 

CSHELL  "LIST  samplefile"  (♦  list  the  new  file. 

DCHD  ".,"  (»  male  the  ROOT  the  data  directory, 

DSHELL  "DEL  TEST/sarcplefile"  (»  delete  the  file. 

DSHELL  "DELDIR  TEST"  (*  delete  the  directory. 

ZiEND 
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CHR$    Return  ASCII  character 


Syntax:      CHR$(eode) 

Function:  Returns  the  ASCII  character  for  the  value  of  code. 
CHR$  is  the  inverse  of  the  ASC  function,  which  returns  the 
ASCII  code  for  a  given  character.  For  a  complete  listing  of 
ASCII  codes,  see  Chapter  9, 

Parameters: 

code  The  ASCII  value  for  a  keyboard  character  or 

special  block  graphics  character. 

Examples: 

PRINT  CHR$C88) 

Sample  Program: 

By  increasing  by  one  the  ASCII  values  of  characters  you  type, 
the  following  program  creates  a  secret  code.  It  uses  CHR$  to  dis- 
play the  secret  code. 

PROCEDURE  secret 
□DIMTE)(T,SECRETllNE:STR!N6t88i 
DDiH  T.CODECHAR: INTEGER 
DTEXT«"" 
DSECRETLINE 

DPR  INT  "Type  a  line  to  code  in  capital  letters,.." 

GINPUT  TEXT  (»  you  type  a  line. 

JFDR  M  TO  LEN(TEXT) 

ZC0DE0HAR°ASC(MIDI(TE!(T,T,1))  <«  loot  at  each  character  in  line. 

FJIF  CODECHAR'90  THEN  <<  is  it  "Z"?  If  yes  then 

CCODECHAR'64  («  make  it  one  less  than  "ft". 

□END IF 

□IF  CODECHftR-32  THEN  (•  is  character  a  space?  If  yes  then 

□CDDECHAR=31  (»  decrease  its  value  by  one. 

□END IF 

Z!SECRETlINE=SEORETLlNE»CHRKCODECHAR<n  U  add  1  to  characters. 

□NEXT  T 

DPRINT  SECRETLINE  (»  print  the  secret  code. 

CEND 
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C-riX    Change  execution  directory 
Cy-HD    Change  data  directory 

Syntax:      CHX  dirpath 
CHD  dirpath 

Function:  Changes  the  current  execution  or  data  directory. 

Parameters: 

dirpath  An  existing  execution  or  data  directory. 

Examples: 

CHX  "/D1/CMDS" 

CHD  "/D1 /ACCOUNTS/RECEIVABLE" 

CHD 
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i^i-AjOhi    Deallocate  file  or  device  path 


Syntax:       CLOSE  #pathnum 


Function:  Deallocates  the  file  or  device  path  specified  by 
pathnum. 

When  you  OPEN  or  CREATE  a  file,  BASIC09  allocates  a  path 
number  to  the  variable  you  supply  in  the  OPEN  or  CREATE 
command.  The  system  then  knows  the  path  by  that  number.  If 
the  path  you  CLOSE  is  to  a  non-shareable  device  (such  as  a 
printer),  the  system  releases  the  device  for  other  use.  Do  not 
close  paths  0,  1,  and  2  (the  standard  I/O  paths)  unless  you 
immediately  open  a  new  path  to  take  over  the  standard  path 
number. 

Parameters: 

pathnum  The  name  of  variable  containing  the  path 

number  or  the  actual  number  of  the  path  to  a 
file  or  device. 

Examples: 

CLOSE  #FILEPflTH,  /PRINTERPflTH ,  #TERMPATH 

CLOSE  '5,  '6,  II 

CLOSE  #1    \   (*  closes  the  standard  output  path  •  ) 
OPEN  #PATH,"/Tr    V  (•  redirects  standard  output  O 

Sample  Program: 

This  procedure  creates  a  directory  named  TEST  and  changes  it 
to  the  data  directory.  It  then  creates  a  file  named  Samplefile  and 
writes  data  to  the  file.  Finally  it  changes  back  to  the  parent 
directory  and  deletes  Samplefile  and  TEST. 
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PROCEDURE  close 

3)  IN  PflTHsBVTE 

jSHELL  "MAKDIR  TEST" 

HCHD  "TEST" 

HCREflTE  *PflTH,"saniplefile":WR!TE  (♦  create  a  new  file, 

jWRITE  *PATH,"Thia  file  is  for  testing  only." 

3IRITE  *PATH,"M  will  be  destroyed  when  this  procedure  ends." 

LCLDSE  *PATH  (*  close  the  file. 

CSHELl  "LIST  sampleflle" 

DCHB  ".," 

DSHELL  "DELD1R  TEST" 

DEND 


11-21 


BASIC09  Reference 


COS 


Return  cosine 


Syntax:      COSCnumfoer) 

Function:  Calculates  the  cosine  of  number.  Unless  you  specify 
DEG,  COS  interprets  the  value  of  number  in  radians. 

Parameters: 

number  The  number  for  which  you  want  to  find  the 

cosine. 

Examples: 

PRINT  C0S<4H) 

Sample  Program: 

This  procedure  calculates  sine,  cosine,  and  tangent  of  a  value 
you  enter. 

PROCEDURE  ratiocalc 

DDIM  MUM: REAL 

CDEG 

CINPUT  "Enter  a  number .. .",NUM 

DPRINT 

DPR  INT  "Number" , "S I NE" , "COSINE" , "TAN" 

DPRINT" 


DPRINT  ANGLE,SIN(NUM),COS(NUM),TANCNUM) 

DPRINT 

DEND 
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CREATE     Establish  a  disk  file. 


Syntax: 

CREATE  #path,"pathlis1?'  [access  mode) 

[  +  access  mode][  + ...] 


Function:  Creates  a  file  on  a  disk.  When  you  create  a  file,  you 
can  select  one  or  more  of  the  following  access  modes  for  the 
file: 


Mode 


Function 


READ 

WRITE 

UPDATE 

Parameters: 

path 

pathlist 
access  mode 


Lets  you  read  (receive)  data  from  a  file  but 
does  not  let  you  write  (send)  data  to  the  file. 

Lets  you  write  data  to  a  file  but  does  not  let 
you  read  data  from  a  file. 

Lets  you  both  read  from  and  write  to  a  file. 


The  name  of  the  variable  in  which  BASIC09 
stores  the  number  of  the  opened  path. 

The  route  to  the  file  or  device  to  be  opened, 
including  the  filename,  if  appropriate. 

The  type  of  access  to  be  allowed  for  the  file  or 
device.  Use  plus  symbols  to  allow  more  than 
one  type  of  access  with  a  single  file. 


Notes: 


"Kai  can  access  files  either  sequentially  or  randomly.  With 
random  access,  you  must  establish  the  filing  system  you 
want  for  a  particular  application. 

Files  are  byte-addressed,  and  you  are  not  restricted  by 
explicit  record  lengths.  You  can  read  the  data  one  byte  at  a 
time,  or  in  whatever  size  portions  you  want. 
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•  A  new  file  has  a  size  of  zero.  OS-9  then  expands  the  file 
automatically  when  PRINT,  WRITE,  or  PUT  statements 
write  beyond  the  current  end-of-file. 

Examples: 

CREATE  #TRANS, "transportation": UPDATE 
CREATE  #SP00L,M/u3er4/report"; WRITE 
CREATE  #OUTPATH,name$:UPDATE+EXEC 

Sample  Program: 

This  procedure  CREATES  a  directory  named  TEST  and  makes  it 
the  data  directory.  It  creates  a  file  in  TEST  named  Samplefile, 
writes  data  to  the  file,  then  resets  the  parent  directory  as  the 
data  directory.  Finally,  it  deletes  Samplefile  and  TEST. 

PROCEDURE  close 

DDIR  PATH! BYTE 

DSHELL  "MAKOIR  TEST" 

DCHD  "TEST" 

QCREATE  #PATH, "samplefile'*! WRITE  («  create  a  file. 

DWRITE  'PATH, "This  file  is  for  testing  purposes  only." 

DWR1TE  'PATH,"]t  will  be  destroyed  when  this  procedure  ends." 

DCLOSE  'PATH  («  close  the  file. 

CSHELL  "LIST  samplefile" 

DCHD  ".." 

DSHELL  "DELDIR  TEST" 

DEND 
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DA.1  A    Store  numeric  and  string  information 


Syntax:      DATA  "ifem"[,"item",...] 


Function:  Stores  numeric  and  string  constants  to  be  accessed 
by  a  READ  statement.  A  DATA  line  can  contain  up  to  254 
characters.  Each  item  in  the  list  must  be  separated  by 
commas. 

You  can  place  DATA  statements  anywhere  in  a  procedure  that 
is  convenient.  BASIC09  reads  sequentially,  starting  with  the 
first  item  in  the  first  DATA  statement,  and  ending  with  the 
last  item  in  the  last  DATA  statement. 

The  following  rules  apply  to  data  items: 

•  You  must  place  all  string  data  between  quotation  marks. 

•  To  include  quotes  in  string-type  data,  use  consecutive 
quotation  marks,  like  this:  data  "He  said,  ""go 
home""    to   me". 

•  You  can  use  RESTORE  to  reset  the  data  pointer.  Using 
RESTORE  without  an  argument  resets  the  pointer  to  the 
beginning  of  the  data  items.  Using  RESTORE  with  a 
line  number,  resets  the  pointer  to  the  first  item  in  the 
specified  line. 

•  The  READ  statement  can  support  a  list  of  one  or  more 
variable  names  of  various  types.  The  data  types  in  DATA 
statements  must  match  the  variable  types  used  in  the 
corresponding  READ  statements. 

•  You  can  include  arithmetic  expressions  in  data  items. 
READ  causes  the  expressions  to  be  evaluated  and 
returns  the  result  of  the  expression  as  the  data  item, 

Parameters: 

item  Numeric  or  string  characters.  Enclose  string 

characters  in  quotation  marks. 


11-25 


BASIC09  Reference 


Examples: 

DATA  1.1,1 .5, 9999, "CAT", "DOG" 
DATA  SINCTEMP/25),  COS<TEMP*PI> 
DATA  TRUE, FAtSE.TRUE, TRUE, FALSE 

DATA  "The  rain  in  spain" ,"f alls  mainly  on  the 
plai  n" 

Sample  Program: 

This  procedure  calculates  the  day  of  the  week  for  a  date  you 
enter.  A  data  statement  contains  the  names  of  the  weekdays, 

PROCEDURE  weekday 

CDIM  X.DAY, MONTH, YEAR, CALC: INTEGER 

DDIM  ANUM,BNUM,CNUM,DNUM,ENUM,FNUM,GNUM,HNUM, INUM: 

INTEGER 

DDIM  WEEKDAYC7>:STRING[9) 

GPRINT  USING  "SG0*" ,"Day  of  the  Week  Program" 

DPRINT  USING  "S60*,,,"For  any  year  after  1752" 

DPR  I  NT 

DINPUT  "Enter  day  of  the  month  as  two  digits,  such 

as  08. . .",DAY 

DINPUT  "Enter  month  as  two  digits,  such  as 

12. . .".MONTH 

DINPUT  "Enter  year  as  four  digits,  such  as 

1986. . .".YEAR 

DFOR  X-1  TD  7 

DREAD  WEEKDAYCX) 

DNEXT  X 

DANUMMNTC.6+1/M0NTH) 

DBNUM-YEAR-ANUM 

DCNUM-MDNTH+1  2«ANUM 

DDNUM-BNUM/iaa 

DENUM-INTCDNUM/4) 

GFNUM=INT(DNUM) 

DGNUM-INT(5*BNUM/4) 

DHNUM-INTC13»(CNUM+1)/5) 

DINUM-HNUM+GNUM-FNUM+ENUM+DAY-1 

DINUM«INUM-7*INT(INUM/7)+1 

DPRINT 

DPRINT  "The  day  of  the  week  on  " j  DAY;  "/";  MONTH; 

OPRINT  "/";  YEAR;  "  is...";  WEEKDAYC I NUM) 

DDATA  "Sunday", "Monday", "Tuesday" ."Wednesday", 

"Thursday" 

DDATA  "Friday", "Saturday" 

[]END 
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DAI  l!jtj>    Provide  date  and  time 


Syntax:      DATE$ 

Function:  Returns  the  date  and  time.  The  OS-9  internal  date 
is  kept  in  the  format: 

year/ month/ day  hour.minutesiseconds 

If  your  OS-9  Startup  file  contains  the  SETIME  command,  the 
system  asks  you  to  enter  the  date  and  time  whenever  it  boots. 
If  it  does  not  contain  the  SETIME  command,  the  date  and 
time  start  from  86/09/01:00:00:00. 

You  can  use  the  normal  string  functions  to  access  the  data 
contained  in  DATE$,  but  you  cannot  use  functions  or  opera- 
tions that  attempt  to  change  or  append  to  its  values.  To  reset 
the  date  or  time  or  both,  use  the  SHELL  command,  such  as: 

SHELL    "SETIME" 

Parameters:  None 
Examples: 

PRINT   DATES 

Sample  Program: 

This  program  is  essentially  the  same  as  the  sample  program  for 
the  DATA  statement,  except  that  it  gets  the  day,  month,  and 
year  from  DATE$. 

PROCEDURE  date 

31M  X, DAY, MONTH, YEAR, CALC: INTEGER 

3DIM  ANUII.BNUM.CNUn.DNUPI.EHUM.FNUM.GNUM.HNUII.INUM: INTEGER 

jDIM  WEEKDAYS)  :STRINGt91 

JM0NTH«VAL(MID$(DATE$,4,S))  (»  get  month  from  DATE*. 

jDAY'VAL{MID*(DATEt,7,2)]  (•  get  day  from  DATE*. 

LYEAR«VAL("19"+LEFTI(DATEI,2))  (»  get  year  from  DATE*. 

L"F0R  X-1  TO  7 
DREAD  WEEKDAYS] 
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DNEXT  X 

QANUM=IHT(.S*1/MDNTH> 

aBNUM-YEfiR-AWJM 

GCN(J)1*M0NTH*1 2*ANUM 

GDHUM-BNUH/llt 

GENUM=IHT(DHUM/4> 

aFNUM'IHT(DHUM) 

aGNUM-IHT(5»BHUM/4> 

QHNUM- IHTC1 3»f CHUH+1 >/5) 

HINUM»=HHUM*GNUM-FHUM+ENUM*DAY-1 

DIHUM-INUH-7*[HTCIHUn/7J+1 

EPRItIT 

DPR I NT  "Today  is  ";  WEEKDAY (I HUM) 

DDATfl  "Sunday", "Monday" , "Tue s day" , "Wednesday" , "Thurs day" , "Fr i day" 

DDATA  "Saturday" 

DEHD 
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-U-Cjvt    Return  trigonometric  calculations  in 
degrees 


Syntax:      DEG 


Function:  Causes  a  procedure  to  calculate  trigonometric  val- 
ues in  degrees.  If  you  do  not  include  the  DEG  statement,  pro- 
cedures produce  radian  values. 

Parameters:  None 

Examples: 

DEG 

Sample  Program: 

This  procedure  calculates  the  sine,  cosine,  and  tangent  for  a 
value  you  enter.  Because  it  uses  the  DEG  statement,  it  displays 
the  results  in  degrees. 

PROCEDURE  degcalc 

IDIM  NUfhREAL 

ODEG 

DINPUT  "Enter  a  number  ..." ,NUM 

DPR  I  NT 

DPR  I  NT  "Number" , "S INE" , "CDS INE" , "TAN" 

DPR  I  NT" 


CPRINT   NUM,SIN(NUM>,COS<NUM>,TAN<NUM> 

IPRINT 
3END 
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DELETE    Erase  a  disk  file 


Syntax:      DELETE  "pathname?' 


Function.:  DELETE  removes  a  file  from  disk  storage  and 
releases  the  portion  of  the  disk  on  which  it  resides.  When  you 
DELETE  a  file,  it  is  permanently  lost. 

Parameters: 

pathname  The  complete  pathlist  to  the  file  you  want  to 

delete,  including  the  drive  and  one  or  more 
directories,  if  appropriate.  %u  must  surround 
the  pathlist  with  quotation  marks. 

Examples: 

DELETE   "myfile" 

DELETE    "/D1 /ACCQUNTS/recelvables" 

Sample  Program: 

This  procedure  creates  a  file  named  Samplefile,  writes  data  to 
the  file,  then  closes  it.  It  then  lists  the  file  before  deleting  it. 

PROCEDURE  close 

QDIM  PATH; BYTE 

DCREATE  *PATH, "samplefile": WRITE  (»  create  a  file. 

QUITE  #PATH,"This  file  is  far  testing  purposes  only." 

DIRITE  'PATH, "It  will  be  destroyed  when  this  procedure  ends." 

DCLDSE  'PATH  (•  close  the  file. 

DSHEIL  "LIST  samplefile" 

QDEIETE  "sanplefile" 

QEND 
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DlJVl    Assign  variable  storage 


Syntax:      DIM  variabH,...][itype][;variable][,...][itype][...] 

Function:  Assigns  storage  space  and  declares  types  for  vari- 
ables, arrays,  or  complex  data  structures. 

Parameters: 

variable  A  simple  variable,  an  array  structure,  or  a 

complex  data  structure. 

type  BYTE,    INTEGER,    REAL,    BOOLEAN, 

STRING,  or  user  defined. 

Notes: 

•  You  declare  simple  arrays  with  DIM  by  using  the  variable 
name,  without  a  subscript.  If  you  do  not  explicitly  declare 
variables,  the  system  makes  them  type  real  unless  they  are 
followed  by  a  dollar  sign  ($).  The  system  dimensions  vari- 
ables ending  with  a  dollar  sign  ($)  as  strings,  with  a  length 
of  32  bytes.  "5fou  must  declare  types  of  all  other  simple  vari- 
ables as  to  type. 

•  You  can  declare  several  variables  of  the  same  type  by  sepa- 
rating them  with  commas.  To  separate  variables  of  differ- 
ent types,  follow  each  type  group  with  a  colon,  the  type 
name,  and  then  a  semicolon. 

•  Define  a  maximum  length  for  a  string  variable  by  enclosing 
the  length  in  brackets  following  the  type,  like  this: 

DIM   name: str ing[25] 
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If  you  do  not  define  a  maximum  length,  BASIC09  uses  a 
default  length  of  32  characters.  You  can  declare  a  shorter 
length  or  a  longer  length,  up  to  the  capacity  of  BASIC09's 
memory.  If  you  try  to  extend  a  string  beyond  its  declared 
length,  or  beyond  the  default  length,  the  system  ignores  all 
extra  characters.  Thus  the  following: 

DIM    name:  str  IngM  0] 
nesme    -    "Abber nathinsky" 

produces  the  string: 

Abber nathi 

•  Arrays  can  have  one,  two,  or  three  dimensions.  The  DIM 
format  for  dimensioned  arrays  is  the  same  as  for  simple 
variables,  except  that  you  must  follow  each  array  name 
with  a  subscript,  enclosed  in  parentheses,  to  indicate  its 
size.  The  maximum  array  size  is  32767. 

Arrays  can  be  either  of  the  standard  BASIC09  type  or  of  a 
user-defined  type.  For  information  on  creating  your  own 
types  for  simple  variables,  arrays,  and  complex  data  struc- 
tures, see  TYPE. 

Examples: 

DIM  logical:BOQLEAN 
DIM  a,b,c:INTEGER 

DIM  name, address ,zip:STRING 

DIM  name: 5TRINGC2S] ;  add rea 5 : STR I NG [ 30 ] ; 
zip: INTEGER 

DIM  no1  ,no2,no3: REAL ; no4 , no5 , no6 : .  INTEGER; 

no7:BYTE 
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Sample  Program: 

This  procedure  randomly  selects  letters  and  vowels  to  create  six- 
letter  words  that  might  look  like  alien  names.  It  first  DIMs  nine 
string  variables  to  contain  the  letters  selected  for  each  name.  It 
DIMs  two  integer  variables  to  provide  a  loop  counter  and  to  store 
the  number  of  names  you  request. 

When  asked,  type  the  number  of  names  you  want  to  have  the 
procedure  generate. 

PROCEDURE  alien 

DDIM  B, BEGIN, F .FINISH: STRING 

DDIM  VOWELS, V0WEL1 ,V0WEL2:STRING 

DDIM  MIDI ,MID2:STRING 

DDIM  T.RESPONSE: INTEGER 

DVOWELS-"aeiouy" 

DINPUT  "How  many  alien  names  do  you  want  to 
see?. . .", RESPONSE 

JBEGIN="ABCDFGHJKLMNPRSTVWXZ" 
HFINI SH*"ehlmnprs tvwyz" 

DFOR  T-1  TO  RESPONSE 
0B=MID$CBEGIN,RND<19)  +  1  ,1) 
0F-MID*<FINISH,RND(12)H ,1) 
DMID1 -CHR$(RND(2E)+97> 
DMID2-CHR$(RNDC2S>+97) 
rV0WEL1=MID$CV0WELS,RND<5)  +  1  ,1) 
JV0WEL2*MID$CV0WELS,RND<S)+1  ,1) 
DPRINT  B;  V0WEL1 j  MIDI;  MID2;  VDWEL2;  F, 
DNEXT  T 

DPRINT 

DEND 
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DO    Execute  procedure  lines  in  a  loop 


Syntax:      WHILE  expression  DO 
proclines 
ENDWHILE 


Function:  Establishes  a  loop  that  executes  the  procedure  lines 
between  DO  and  ENDWHILE  as  long  as  the  result  of  the 
expression  following  WHILE  is  true.  Because  the  loop  is 
tested  at  the  top,  the  lines  within  the  loop  are  never  executed 
unless  expression  is  true. 

Parameters: 

expression  A  Boolean  expression  (produces  a  result  of 

True  or  False). 

proclines  Are  program  lines  to  execute  if  the  expression 

is  true. 

See  WHILE/DO/ENDWHILE  for  more  information. 
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hiLd&hj    Execute  alternate  action 


Syntax:      IF  condition  THEN 
action 
ELSE 

secondary  action 
ENDIP 


Function:  ELSE  provides  access  to  a  secondary  action  within 
an  IF/THEN  test.  When  the  condition  tested  by  IF  is  not 
true,  BASIC09  executes  the  secondary  action  preceded  by 
ELSE. 

Parameters: 

condition  A  Boolean  expression  (produces  a  result  of 

True  or  False). 

action  A  line  number  to  which  the  procedure  is  to 

transfer  execution,  or  a  program  statement.  If 
action  is  a  line  number,  do  not  include  the 
ENDIF  statement  in  the  IF  test. 

secondary  One  or  more  program  statements. 

action 

For  more  information,  see  IF/THEN/ELSE 
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Ej  JN  D    Terminate  a  procedure 


Syntax:      END  ["text'] 

Function:  Ends  procedure  execution  and  returns  to  the  calling 
procedure,  or  to  the  highest  level  procedure.  If  you  provide 
output  text  for  END,  it  functions  in  the  same  manner  as 
PRINT.  You  can  use  END  several  times  in  the  same  proce- 
dure. END  is  not  required  as  the  last  statement  in  a 
procedure. 

Parameters: 

text  A  literal  string  or  a  string-type  variable. 

Examples: 

END  "Program  Terminated" 

LAST$  =  "SessiOTi  over" 
END  LAST* 

Sample  Program: 

This  procedure  calculates  a  ban's  term,  using  END  to  termi- 
nate routines. 

PROCEDURE  loaner 

DDIM  YOUP AY, PRINCIPLE, I NTEREST , NUMPAY , YEARS , 

MONTHS: REAL 

DDIM  RESPQNSEiSTRINGM ] 

DREPEAT 

DPR  I  NT 

DPRINT  USING  "S4S*",,,Looti  Terms" 

DPRINT 

HINPUT  "    Amount  of  Regular  Payment s ..." .YOUPAY 

HINPUT  "    Enter  the  Pr i nc iple . . . " , PR  I NC I PLE 

HINPUT  "    Enter  the  Annual  Interest  Rate...", 

INTEREST 

CINPUT  "    Enter  the  Number  of  Payments 

Yearly. . .", NUMPAY 
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CYEARS-~(L0G(1 -PR INCIPLE*< INTEREST/1  00)/ 

<NUMPAY*Y0UPAY))/(L0O(1+ INTEREST/1 0  0/NUMPAY>» 

NUMPAY)) 

DM0NTH-INT<YEARS»12+.S> 

DYEARS=INT(MDNTH/12) 

QM0NTM=MDNTH-YEARS»12 

DPRINT  "    The  Term  of  Your  Loan  is  "j  YEARS; 

years  and  " ;  MONTH;  "  months." 

DINPUT  "Calculate  another  or  Quit  <C/Q>? . . .", 

RESPONSE 

DUNTIL    RESPQNSEo"C"   AND   RESPONSE<>"c" 

GEND    "Goodbye... I    hope    I    helped   you." 
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Jii^l  Dili  A.1 1     Leave  loop  if  a  condition  is  True 


Syntax:       EXITIP  condition  THEN 
proclines 
ENDEXIT 


Function:  ENDEXIT  terminates  an  EXITIF  test.  You  always 
use  EXITIF/THEN/ENDEXIT  inside  a  procedure  loop.  If  the 
Boolean  expression  tested  by  EXITIF  is  true,  BASIC09  exe- 
cutes the  program  statements  between  THEN  and  ENDEXIT 
and  then  transfers  program  operation  outside  the  loop.  If  the 
condition  tested  by  EXITIF  is  not  true,  loop  execution  contin- 
ues at  the  statement  following  ENDEXIT. 

Parameters: 

condition  A  comparison  operation  that  returns  either 

True  or  False,  such   as  A  =  B,  A<B,  or 
A=B  =  C. 

proclines  One  or  more  statements  to  perform  if  the  Boo- 

lean expression  tested  by  EXITIF  is  True. 

For  more  information,  see  EXITIF/THEN/ENDEXIT 
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ENDIF     Close  IF  statement 


Syntax:       IF  condition  THEN 
action 
[ELSE 

secondary  action] 
ENDIF 


Function:  ENDIF  terminates  an  IF/THEN  condition  test.  If 
the  condition  tested  by  IF  is  true,  BASIC09  executes  the 
statements  between  THEN  and  ENDIF.  If  the  condition  tested 
by  IF  is  not  true,  BASIC09  transfers  execution  to  the  proce- 
dure line  following  ENDIF  or  (optionally)  executes  the  state- 
ments following  ELSE. 

Parameters: 

condition  A  Boolean  expression  (produces  a  result  of 

True  or  False). 

action  A  line  number  to  which  the  procedure  is  to 

transfer  execution.  Action  can  also  be  a  pro- 
gram statement.  If  action  is  a  line  number,  do 
not  include  the  ENDIF  statement  in  the  IF 
test. 

secondary  A  program  statement. 

action 

For  more  information,  see  IF/THEN/ELSE/ENDIF. 
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ENDLOOP     Close  LOOP  statement 


Syntax:      LOOP 

statements) 
ENDLOOP 


Function:  ENDLOOP  terminates  a  procedure  loop  established 
by  the  LOOP  command,  BASIC09  endlessly  executes  all  proce- 
dure statements  between  LOOP  and  ENDLOOP  repeatedly 
unless  a  condition  test  within  the  loop  (such  as  EXITIF/ 
THEN/ENDEXIT,  or  IF/THEN)  transfers  execution  outside  of 
the  loop. 

Parameters: 

statements)       One  or  more  procedure  lines  that  execute 
within  the  loop. 

For  more  information,  see  LOOP/ENDLOOP. 
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ENDWHILE     Close  WHILE  statement 


Syntax:       WHILE  condition  DO 
proclines 
ENDWHILE 


Function:  Forms  the  bottom  of  a  WHILE  loop.  WHILE  causes 
the  procedure  lines  between  DO  and  ENDWHILE  to  execute 
as  long  as  the  result  of  the  expression  following  WHILE  is 
true.  Because  the  loop  is  tested  at  the  top,  the  lines  within 
the  loop  are  never  executed  unless  the  expression  is  true. 

Parameters: 

condition  A  Boolean  expression  (produces  results  of  True 

or  False). 

proclines  Are  program  lines  to  execute  if  the  expression 

is  true. 

For  more  information,  see  WHILE/DO/ENDWHILE. 
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EOF 


Test  for  end-of-file 


Syntax:      EOF(path) 


Function:  Tests  for  the  end  of  a  disk  file.  The  function  returns 

a  value  of  True  when  it  encounters  an  end-of-file;  otherwise,  it 
returns  False.  Use  EOF  with  a  READ  or  GET  statement. 

Parameters: 

path  The  number  of  the  path  you  are  accessing. 

BASIC09  automatically  stores  a  path  number 
into  the  variable  you  specify  during  a 
CREATE  or  OPEN  operation. 

Examples: 

IF  EOFC#PATH)  THEN 
CLOSE  #PATH 
ENDIF 

Sample  Program: 

This  procedure  redirects  a  listing  of  the  current  directory  into  a 
file  named  Dirfile.  It  then  lists  Dirfile  to  the  screen.  EOF  tells 
the  WHILE/ENDWHILE  loop  when  the  READ  operation  reaches 
the  end  of  the  file. 

PROCEDURE  readfile 

CDIM  A:STRING[80] 

CDIM  PATHrBYTE 

CSHELL  "DIR  >  dirfile" 

DOPEN  #PATH,"dirf ile":READ 

QWHILE  NOT  EOF(#PATH)  DO 

DREAD  #PATH,A 

DPR  I  NT  A 

DENDWHILE 

DCLOSE  #PATH 

DEND 
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Ej  xCxC    Return  error  code 


Syntax:      ERR 

Function:  Returns  the  error  code  of  the  most  recent  error. 
BASIC09  automatically  sets  the  ERR  code  to  zero  after  you 
reference  it,  ERR  is  only  useful  when  used  in  conjunction  with 
BASIC09's  ON  ERROR  error  trapping  functions. 

See  Appendix  A  for  a  list  of  all  BASIC09  error  codes. 
Parameters:  None 
Examples: 

ERRNUM   -    ERR 

IF  ERRNUM  -  218  THEN 

PRINT  "File  already  exists.  Please  use  another 

f i lename . " 

ENDIF 

Sample  Program: 

This  procedure  displays  the  contents  of  a  file  you  select.  If  the 
file  doesn't  exist  (Error  216,  Pathname  not  found),  the  procedure 
uses  ERR  to  tell  you.  If  an  error  other  than  Error  216  occurs, 
the  procedure  displays  I  can't  handle  error  xx,  where  xx  is 
the  code  of  the  error. 
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PROCEDURE  readfile 

CD1M  READFILE: STRING;  AiSTRINGIBBl;  PATH: BYTE 

16DINPUT  "Type  the  pathlist  of  the  file  to  read.. .".READF1LE 

CON  ERROR  GOTO  111    (•  if  an  error  occurs,  skip  to  line  168. 

COPEN  *PATH,READFILE:READ 

[MILE  EDF('PATHX>TRUE  DO 

DREAD  /PATH, A 

DPR  INT  A 

DENDWHILE 

DOLOSE  'PATH 

DEND 

lSBDERRNUM'ERR  (»  store  the  error  code  in  ERRNUM, 

DIF  ERRNUM'216  THEN  (•  if  file  doesn't  exist  say  so. 

QPRINT  "I  can't  find  the  file... Please  try  again." 

DON  ERROR 

D60T0  18 

DEND IF 

DPRINT  "Sorry,  !  can't  handle  error  number  "j  ERRNUM  (»  other  error. 

LCLDSE  'PATH 

DEND 
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Jjj.KxvO.tv    Simulate  an  error 


Syntax:      ERROR  code 


Function:  Simulates  the  error  specified  by  cock.  You  would 
mainly  use  this  command  to  test  ON  ERROR  GOTO  routines. 
When  BASIC09  encounters  an  ERROR  statement,  it  proceeds 
as  if  the  error  corresponding  to  the  specified  code  has 
occurred.  Refer  to  Appendix  A  for  a  listing  of  error  codes  and 
their  meanings. 

Parameters: 

cock  The  code  of  the  error  you  want  to  simulate. 

Examples: 

ERROR    207 

ERRNUM    -    ERR 

IF  ERRNUM  ■  207  THEN 

PRINT  "Memory  is  full.  The  current  data  is  being 

saved  to  disk." 

ENDIF 

Sample  Program: 

This  program  creates  a  file  named  Testl.  Before  creating  the 
file,  it  checks  to  see  if  it  already  exists.  If  the  file  exists,  the  pro- 
cedure deletes  it.  An  error  trap  catches  any  error  that  might 
occur.  To  test  if  the  trap  works  for  Error  216,  "Pathname  not 
found",  the  statement  ERROR  216  is  inserted  as  the  fourth  line. 
After  testing  the  trap  to  make  sure  it  works,  delete  this  line  to 
use  the  procedure. 
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PROCEDURE   errortest 

DDIM   PATH, ERRNUM: BYTE;    RESPONSE rSTRINCM ] 

DBASE    0 

DON  ERROR  60T0  10     (*  set  error  trap 

DERROR  216  t*  simulate  error 

DDELETE  "testl" 

DGOTD  100 

10OERRNUM-ERR 

□IF  ERRNUM-216  THEN 

DINPUT  "File  doesn't  exist .. .continue? 

<Y/N)M,RESPDNSE 

DIF  RESP0NSE-"N"  THEN 

DEND   "Procedure    terminated   at    your    request...' 

DENDIF 

DEND  IF 

DON   ERROR  (*    turn   off    error    trap. 

100OCREATE    #PATH,"te5t1":WRITE 

□END 
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EXITIF/THEN/ENDEXIT 

Exit  from  loop  if  a  condition  is  true 


Syntax:       EXITIF  condition  THEN 
statement 
ENDEXIT 


Function:  Use  these  statements  with  loop  constructions  (par- 
ticularly LOOP  and  ENDLOOP)  to  provide  an  exit  for  what  is 
otherwise  an  endles9  loop.  EXITIF  performs  a  test  of  a  Boo- 
lean expression,  such  as  A<B.  The  THEN  statement  precedes 
any  operation  you  want  to  execute  if  the  expression  is  true. 
You  must  always  follow  EXITIF  with  an  ENDEXIT. 

If  the  Boolean  expression  following  an  EXITIF  is  false,  execu- 
tion of  the  program  transfers  to  the  statement  immediately 
following  the  body  of  the  loop  (after  the  ENDEXIT  statement). 
Otherwise,  BASIC09  executes  the  statement(s)  between 
EXITIF  and  ENDEXIT,  then  transfers  control  to  the  state- 
ment following  the  body  of  the  loop. 

You  can  also  use  EXITIF  and  ENDEXIT  with  types  of  bop 
constructions  other  than  LOOP/ENDLOOP. 


Parameters: 

Boolean 
expression 


statement 


A  comparison  operation  that  returns  either 
True  or  False,  such  as  A  =  B,  A<B,  or 
A=B  =  C. 

An  operation  to  be  performed  if  the  Boolean 

expression  tested  by  EXITIF  is  True,  such  as: 
PRINT   A    is    less    than   B. 
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Examples: 

LOOP 

C0UNT-C0UNT+1 

EXITIF  COUNTM00  THEN 

DONE  «  TRUE 

ENDEXIT 

PRINT  COUNT 

X  =  COUNT/2 

ENDLOOP 

Sample  Program: 

This  procedure  simulates  a  gambling  machine  by  randomly 
selecting  among  several  fruit  names  and  displaying  them.  It 
gives  you  a  starting  stake  of  $25  and,  depending  on  the  combi- 
nation of  fruit  selected,  it  adds  or  subtracts  from  your  stake. 

If  your  stake  drops  to  zero,  an  EXITIF  statement  ends  the  proce- 
dure and  tells  you  that  you're  broke. 

PROCEDURE  oneorm 

DDIM  FRUIT1  ,FRUIT2,FRUIT3,STAKE:INTEGER;  FRUIT<8): 

STRIN0C6] 

OSTAKE-25 

GPRINT   \  PRINT  "You  have  $";  STAKE;  "  to  ploy 

with." 

HFDR  T-1  TO  8 

jREAD   FRUITCT) 

jNEXT   T 

XOOP 

DFRUIT1=RND(7>+1     \FRUIT2=RNDC7)*1    \FRUIT3-RND<7)+1 

GPRINT   FRUIT(FRUITU;    "   ";    FRU ITCFRUI T2> ;    "    "; 

FRUIT<FRUIT3) 

DIF    FRUITCFRUIT1)=FRUITCFRUIT2)    AND   FRU IT<FRUI T1 >= 

FRUITCFRUIT3J    THEN   STAKE-STAKE+1 0 

DELSE 

DIF    FRUITCFRUITD-FRUITCFRUIT2)    OR    FRU IT<FRUI T1 >- 

FRUITCFRUIT3)    OR 

DFRUIT<FRUIT2)-FRUIT(FRUIT3)    THEN 

DSTAKE=>STAKE  +  1 

DELSE 

DSTAKE-STAKE-1 

DENDIF 

DENDIF 
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DREM   exit    play    loop    is    stake    is    leas    than    $1, 

DEXITIF    STAKE<1    THEN 

DPR  I  NT 

GPR1NT   "You're   Busted. . .Bet ter    go    home." 

DENDEX1T 

IPRINT  "Your  stake  is  now  $";  STAKE;  "." 

CPRINT 

DPR  I  NT 

DINPUT  "Press  ENTER  to  pull  again... ",Z$ 

DENDLGOP 

DEND 

GDATA  "ORANGE" , "APPLE" , "CHERRY" , "LEMON" , "BANANA" 

IDATA  "PE AR", "PLUM", "PEACH" 
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1^X.P    Return  natural  exponent 


Syntax:      EXP<nurober) 

Function:  Returns  the  natural  exponent  of  number,  that  is,  e 
(2.71828183)  to  the  power  of  number.  Number  must  be 
positive. 

This  function  is  the  inverse  of  the  LOG  function.  Therefore, 
number  =  EXP(LOG(number)). 

Parameters: 

number  A  positive  value. 

Examples: 

PRINT   EXP<2) 

Sample  Program: 

This  procedure  calculates  the  exponent  of  values  in  the  range 
0-1. 

PROCEDURE  exprint 

3F0R   T-0    TO    1    STEP    .03 

DPR  I  NT   EXP(T>,EXP<T+.01),EXP(Tt.02> 

DNEXT   T 

3END 
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I'A.IjoJ^    Assign  Boolean  value 


Syntax:      variable=  FALSE 


Function:  FALSE  is  a  Boolean  function  that  always  returns 
False.  You  can  use  FALSE  and  TRUE  to  assign  values  to  Boo- 
lean variables. 

Parameters:  None 

Examples: 

DIM  TEST:BDDLEAN 
TEST-FALSE 

Sample  Program: 

The  procedure  uses  a  Boolean  variable  to  store  True  or  False, 
depending  on  whether  you  answer  some  questions  correctly  or 
incorrectly. 

PROCEDURE  quiz 

DDIM  REPLY, VALUE:BQOLEAN;  ANSWER : STR I NG[ 1  J ; 

QUESTION:STRING[80] 

DFQR  T-1  TO  5 

DREAD   QUESTION.VALUE 

DPRINT    QUESTION 

DPRINT   "CT>    -   TRUEDLTJLTJLTKF)    -   FALSE" 

DPRINT   "Select    T   or    F:DC"} 

DGET   #1 , ANSWER 

DIF    ANSWER-"T"   THEN 

DREPLY-TRUE 

DELSE 

DREPLY-FALSE 

DENDIF 

DIF  REPLY-VALUE  THEN 

DPRINT   \  PRINT  "That's  Correct  ...  Good  Show!" 

DELSE 

DPRINT  "Sorry,  you're  wrong ...  Better  Luck  next 

time." 

CENDIF 

CPRINT      \    PRINT      \    PRINT 
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:next  t 

jDATA  "In  computer  talk,  CPU  stands  for  Central 

Packaging  Unit.",  FALSE 

jDATA  "The  actual  value  of  64K  is  GSS3G 

bytes.", TRUE 

"DATA  "The  bits  in  a  byte  are  normally  numbered 

through  7?", TRUE 

ZDATA  "BASIC09  has  four  data  types .", FALSE 

jDATA  "The  LAND  function  is  a  Boolean  type 

operator .".FALSE 

:end 
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r  1.X    Round  a  real  number 


Syntax:      FIX(  value) 

Function:  Rounds  a  real  number  to  the  nearest  whole  number 
and  converts  it  to  an  integer-type  number.  Fix  performs  a 
function  that  is  the  opposite  of  the  FLOAT  function. 

Parameters: 

value  Any  real  number, 

Examples: 

A-RNDC1 0) 
PRINT  FIXCA) 

Sample  Program: 

This  procedure  displays  the  FIXed  values  of  seven  constants. 

PROCEDURE   printfix 
DPRINT   FIXC1 .2) 
DPRINT   FIXC1 .3) 
DPRINT   FIXC1 .5) 
DPRINT   FIXtl .8) 
DPRINT    FIXC99. 566666) 
DPRINT   FIXC50.1) 
DPRINT   FIXC .7654321 ) 
DPRINT   FIX(-12.44) 
DPRINT   FIX(-9.99) 
DEND 
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h  luKjAl.     Convert  from  integer  or  byte  to  real 


Syntax:      FLOATX  value) 

Function:  Converts  an  integer-  or  byte-type  value  to  real  type. 
FLOAT  performs  a  function  that  is  the  opposite  of  the  FIX 
function. 

Parameters: 

value  An  integer-  or  byte-type  number. 

Examples: 

DIM  TEST: INTEGER 

TEST-44 

PRINT  FL0AT(TEST>/3 

Sample  Program: 

This  procedure  uses  FLOAT  to  produce  a  real  number  result  of 
an  inch  to  centimeter  conversion. 

PROCEDURE  convert 

DDIM  T: INTEGER;  MEASURE :STRINGM  1  1 

DFOR  T=1  TO  10 

DIF  T-1  THEN 

QMEASURE-"centimeter  ■■ 

OELSE 

GMEASURE-"cen timet  era" 

DENDIF 

DPRINT    T;    "   ";    MEASURE;    "    is    ";    FLGATCT)* . 3937 ; 

"    inches." 

CNEXT   T 

CEND 
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FOR/NEXT/STEP    Establish  a  loop 


Syntax: 

FOR  variable  =  init  val  TO  end  val  [STEP  value) 

[procedure  statements] 

NEXT  variable 


Function:  Establishes  a  procedure  loop  that  lets  BASIC09  exe- 
cute one  or  more  procedure  statements  a  specified  number  of 
times.  The  variables  you  use  can  be  either  integer  or  real  type 
and  can  be  negative,  positive,  or  both.  Loops  using  integer 
values  execute  faster  than  loops  using  real  values. 

BASIC09  executes  the  lines  following  the  FOR  statement  until 
it  encounters  a  NEXT  statement.  Then  it  either  increases  or 
decreases  the  initial  value  by  one  (the  default)  or  by  the  value 
given  STEP. 

Parameters: 

variable  Any  legal  numeric  variable  name. 

init  val  Any  numeric  constant  or  variable. 

end  val  Any  numeric  constant  or  variable, 

value  Any  numeric  constant  or  variable. 

procedure  Procedure  lines  you  want  to  be  executed 

statements  within  the  loop. 


Notes: 


If  you  provide  an  initial  value  that  is  greater  than  the  final 
value,  BASIC09  skips  the  program  loop  entirely  unless  you 
specify  a  negative  STEP  value.  Specifying  a  negative  value 
for  STEP  causes  the  loop  to  decrement  from  the  initial 
value  to  the  end  value. 
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When  execution  reaches  the  NEXT  statement  in  a  positive 
stepping  loop,  and  the  step  value  is  less  than  or  equal  to 
the  end  value,  BASIC09  branches  back  to  the  line  after 
FOR  and  repeats  the  process.  When  the  step  value  is 
greater  than  the  end  value,  BASIC09  transfers  execution  to 
the  statement  following  the  NEXT  statement. 

When  execution  reaches  the  NEXT  statement  in  a  negative 
stepping  loop,  and  the  step  value  is  greater  than  or  equal 
to  the  end  value,  BASIC09  branches  back  to  the  line  after 
FOR  and  repeats  the  process.  When  the  step  value  is  less 
than  the  end  value,  execution  continues  following  the  NEXT 
statement. 


Examples: 

FOR  COUNTER  =  1  to  100  STEP  .5 

PRINT  COUNTER 
NEXT  CDUNTER 

FDR  X  =  10  TO  1  STEP  -1 
PRINT  X 
NEXT  X 

FOR  TEST  =  ft  TO  a  STEP  RATE 
PRINT  TEST 
NEXT  TEST 

Sample  Program: 

This  procedure  uses  two  nested  FOR/NEXT  loops  to  produce  a 
multiplication  table. 

PROCEDURE  multable 

DPRINT  USING  "S45"",  "MULTIPLICATION  TABLE" 

DPRINT 

DDIM  I  ,J: INTEGER 

DFOR  1*1  TO  9 

DFOR  J-1  TD  9 

CIF  J>1  THEN 

CPRINT  I*Jj  TAB(S*J); 

EELSE  PRINT  I*J;  "|  "; 

iZENDIF 

CNEXT  J  ' 

GIF  1=1  THEN 

CPRINT  "" 
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DPRINT   * 

-  —  —  II  ■ 

* 

DENDIF 
DPRINT 
□NEXT    I 
OEND 
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Vxll*  1     Read  a  direct-access  file  record 


Syntax:       GET  #path,varname 


Function:  Reads  a  fixed-size  binary  data  record  from  a  file  or 
device.  Use  GET  to  retrieve  data  from  random  access  files. 

Although  you  usually  use  GET  with  files,  you  can  also  use  it 
to  receive  data  for  any  outputting  device,  such  as  a  keyboard 
or  another  computer.  By  dimensioning  a  string  variable  to  the 
length  of  input  you  want,  you  can  use  GET  to  read  a  specified 
number  of  keystrokes,  then  continue  program  execution  with- 
out requiring  |  enter  |  to  be  pressed. 

For  information  about  storing  data  in  random  access  files,  see 
Chapter  8,  "Disk  Files."  Also  see  PUT,  SEEK,  and  SIZE. 

Parameters: 

path  A  variable  name  you  choose  in  which  BASIC09 

stores  the  number  of  the  path  it  opens  to  the 
device  you  specify  or  one  of  the  standard  I/O 
paths  (0,  1,  or  2). 

varname  The  variable  in  which  you  want  to  store  the 

data  read  by  the  GET  statement. 

Examples: 

GET  #PATH,DfiTA$ 

GET  #1 .RESPONSE* 
GET  #INPUT,INDEX<:X) 

Sample  Program: 

This  procedure  directs  a  directory  listing  to  a  file  named  Dirfile. 
GET  then  reads  the  file,  one  character  at  a  time  in  order  to 
determine  which  characters  are  valid  filename  characters.  The 
procedure  creates  a  file  containing  ail  the  filenames  in  the 
directory. 
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PROCEDURE  filenames 

DDIM  DIRECTORY, FILENAME: STRING;  CHARACTER: STRING! 11}  FILESCT 25) :STRINGE 1 S] ; 

PATH, COUNT.T: INTEGER 

CC0ONT=« 

□FILENAME'"" 

DFQR  T'l  TO  125  (•  initialize  array  elements  to  null. 

DFILES(T)-"" 

□NEXT  T 

DIHPUT  "Pathlist  of  directory  to  read... ".DIRECTORY  <♦  dir  to  copy. 

DOH  ERROR  GOTO  IB 

ODELETE  "dirfile"  {«  If  dirfile  already  exists,  delete  it. 

ION  ERROR 

DSHELL  "DIR  "'DIRECTORY*'  >  dirfile"  (»  copy  directory  into  file. 

DOPEN  'PATH,,'dirfile":READ  («  open  the  file  for  reading. 

□REPEAT 

CREM  Get  characters  from  the  file  until  the  first  carriage  return  -  the 

beginning  of  the  first  filename. 

DGET  'PATH, CHARACTER  («  get  characters  from  the  file. 

□UNTIL  CHARACTER'CHRt(13) 

□REM 

2IDLD0P 

DEXITIF  EOFC'PATH)  THEN 

□GOTO  Hi  (•  quit  when  end  of  file. 

□ENDEXIT 

□REM  get  a  character  from  the  file  until  it  finds  a  non-valid  filenane 

character. 

□GET  'PATH, CHARACTER 

□REM 

DEXITIF  CHARACTER*-"  "  OR  CHARACTER)":"  THEN 

G60TO  186 

3ENDEX1T 

□FILENAME«FILENAME*CHARACTER  <«  build  the  filenaee. 

□ENDLQOP 

1IOHILE  NOUEOFCPATH))  DO 

GGET  'PATH, CHARACTER  (»  check  for  non-valid  filename  characters. 

CEXITIF  CHARACTER)"  "  AMD  CHARACTER*-"*"  THEN  (•  check  if  valid  char. 

DCOUNT- COUNT* 1 

DF I LESt COUNT) •FILENAME  ('store  filename  in  array. 

DPRIHT  FILENAME,  (t  display  the  extracted  filename. 

DFILENAME'1"1  (•  set  variable  to  NULL. 

DF I LENAME'F I LENAME* CHARACTER  <»  last  character  begins  new  filename. 

QGOTO  28  (»  go  get  the  rest  of  filename. 

□ENDEXIT 

QENDWHILE 

2SOL0SE  'PATH 
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DDELETE  "dirfile"  (•  names  are  all  in  array  so  delete  file. 

DCREATE  »P(lTH,"dirfUe":WRITE  («  create  the  file  again. 

DFDR  T«1  TD  COUNT 

DWR1TE  #PATH,FILES(T)  (»  fill  the  file  with  individual  filenames, 

DHEXT  T 

DOLOSE  #PATH 

DPR  INT 

DPR  INT  "DnDDDDD'The  directory  has  ";  COUNT  i  "  entries." 

DPRINTDTOLDDDDnThey  are  now  stored  in  a  file  named  Dirfile." 

DEND 


11-60 


BASIC09  Command  Reference  1 11 


GOSUB/RETURN 

Jump  to  subroutine/  Return  from  subroutine 


Syntax:      GOSUB  linenumber 


Function:  Branches  program  execution  to  the  specified  line 
number. 

BASIC09  lets  you  write  programs  with  line  numbers  or  with- 
out. You  can  also  mix  numbered  and  un-numbered  lines 
within  a  single  procedure.  This  means  that,  to  use  GOSUB, 
you  need  to  number  only  the  first  line  of  the  subroutine  to 
which  you  want  to  branch. 

Every  subroutine  you  access  with  GOSUB  must  contain  a 
RETURN  statement.  You  can  call  a  subroutine  in  this  man- 
ner as  many  times  as  you  want.  When  BASIC09  encounters 
the  RETURN,  it  transfers  program  execution  to  the  line  fol- 
lowing the  GOSUB  statement. 

You  can  precede  GOSUB  with  a  test  statement,  such  as  IF  or 
WHEN,  that  makes  branching  conditional. 

You  can  nest  GOSUB  statements  to  any  depth,  depending  on 
your  computer's  free  memory. 

Parameters: 

linenumber        The  number  of  the  line  where  procedure  exe- 
cution is  to  continue. 

Examples: 

GOSUB   100 
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Sample  Program: 

The  following  procedure  asks  you  for  two  numbers  and  an  opera- 
tor. It  determines  the  line  to  jump  to  by  the  position  of  the  oper- 
ator in  a  table.  GOSUB  sends  the  procedure  to  execute  the 
proper  routine.  RETURN  sends  the  execution  back  to  the  main 
routine.  To  quit,  enter  a  negative  value. 

PROCEDURE  calc 

CDIM  NUM1 ,NUM2:REAL;  OP iSTRINGCIl ;  As  INTEGER 

1DINPUT  "NUMBER  1  ";NUM1 

DIF  NUMKf  THEN 

DEND  "THAT'S  ALL" 

DINPUT  "NUMBER  2  ";NUM2 

DINPUT  "OPERATOR  ";0P 

GA-SUBSTRC  OP,  "♦-*/*») 

DON  A  GOSUB  1 0,20,30,40,50 

DGOTO  1 

10DPRINT  NUM1+NUM2  \  RETURN 

28DPRINT  NUM1-NUM2  \  RETURN 

30DPRINT  NUM1»NUM2  \  RETURN 

40DPRINT  NUM1/NUM2  \  RETURN 

S0QPRINT  NUM1  NUM2  \  RETURN 

CEND 
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IF/THEN/ELSE/ENDIF 


Test  a  Boolean  expression 


Syntax:       IF  condition  THEN  hnenumber 
[ELSE 

secondary  action 
ENDIF] 

IF  condition  THEN 

action 

[ELSE 

secondary  action] 

ENDIF 


Function:  Tests  a  Boolean  expression  and  executes  action  if  the 
expression  is  true.  Optionally,  the  statements  execute  a  sec- 
ondary action  if  the  expression  is  not  true.  Each  IF  statement 
must  be  accompanied  by  THEN.  If  action  is  a  line  number, 
you  can  omit  the  ENDIF  statement.  For  instance,  both  of  the 
following  statements  operate  in  the  same  manner: 

IF   T=S   THEN    10 

IF  T-S  THEN 
GOTO  10 
ENDIF 


Parameters: 

condition 
Hnenumber 

action 


secondary 
action 


A  Boolean  expression  (produces  True  or  False). 

A  line  to  which  the  procedure  is  to  transfer 
execution  if  condition  is  true. 

One  or  more  procedure  statements  to  be  exe- 
cuted if  condition  is  true. 

One  or  more  procedure  statements  to  execute 
if  condition  is  false. 
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Examples: 

IF  A>B  THEN  100 

IF  A«E  THEN  100 

ELSE 

A-A-1 

ENDIF 

IF  TEST-TRUE  THEN 

PRINT  "The  test  is  a  success..." 

ENDIF 

IF  M  B  THEN 

PRINT  "A  is  less  than  B" 

ELSE 

PRINT  "B  is  less  than  A" 

ENDIF 

Sample  Program: 

The  following  procedure  is  a  purge  procedure.  Use  it  only  with 
the  GET  Sample  Program  to  delete  one  or  more  files  from  your 
current  directory. 

The  Filenames  procedure  (see  GET)  stores  the  current  directo- 
ry's filenames  in  Dirfile.  This  procedure  reads  Dirfile,  displays 
all  the  filenames,  then  asks  you  for  a  wildcard.  Type  in  charac- 
ters that  identify  a  group  of  files  you  want  to  delete.  The  pro- 
gram deletes  all  files  that  contain,  in  the  same  order  and  case, 
the  characters  you  type. 

For  instance,  if  you  have  four  files  named  Test,  Filel,  File2,  and 
File3,  and  you  type  a  wildcard  of  "File,"  the  procedure  deletes 
Filel,  File2,  and  File3,  but  does  not  delete  Test.  Delete  all  of  the 
files  in  a  directory  by  typing  "*"  as  the  wildcard. 

Use  this  program  carefully.  Be  sure  you  are  in  the  right 
directory  and  that  the  wildcard  characters  you  type  are  not  con- 
tained in  filenames  other  than  the  ones  you  want  to  delete.  Ifou 
might  want  to  add  a  prompt  to  the  procedure  that  lets  you  con- 
firm each  deletion  before  it  happens. 
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PROCEDURE  purge 

QDIM  PATH: INTEGER 

QDIM  NAMEC100);STRING 

DDIM  WILDCARDrSTRING 

□X*0 

DOPEN    #PATH,"dlrf  He"iREAD 

DWHILE  NQT<EOF<#PATH))  DO 

L"X«=X  +  1 

jread  #path,namecx) 
:endwhile 
hfor  t-1  td  x 
gprint  namect), 

QNEXT  T 

□INPUT  "Wildcard  Characters  ..." .WILDCARD 

DFOR  T-1  TD  X 

DON  ERROR  GOTO  100 

DIF  SUBSTRCWILDCARD,NAME<T)>>0  OR  WILDCARD= 

THEN 

□PRINT  "DELETING  ";  NAME(T)j  "  " 

DDELETE  NAME(T) 

□ENDIF 

1 0HNEXT  T 

□END 

100CPRINT  "»  *  *  ERROR  *  *  #  ";  NAME(T);  "  cannot 

be  del eted . . cont inuing . " 

"GOTO  10 
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Lrii\.hj  I     Read  a  keypress 


Syntax:      KUN  INKEY(strwg) 


Function:  Reads  a  keypress,  and  stores  the  character  of  the 
key  in  the  specified  string  variable. 

Parameters: 

string  is  a  string  variable  into  which  INKEY  stores 

the  character  you  press. 

Examples: 

DIM  CHAR:STRING[11 

CHAR-"" 

WHILE  CHAR=""  DO 

RUN  INKEYCCHAR) 

ENDWHILE 

PRINT  ASCCCHAR) 
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Sample  Program: 


PROCEDURE  Calculate 

HDIM  CHARjSTRINGCI ] 

LDIM  LDDKUPjSTRINGC7] 

CDIM  FIRST,SECOND;REAL 

DDIM  FLAG: INTEGER 

0L0OKUP-"<--*/*<>" 

1  FLAG-0  \CHAR-"" 

DPRINT  "Enter  the  first  number  to  evaluate. . ."; 

DINPUT  FIRST 

DIF  FIRST*0  THEN 

HGOTO  100 

CENDIF 

DPRINT  "Enter  the  second  number  to  evaluate..."; 

DINPUT  SECOND 

CPRINT  "Press  the  key  of  the  operator  you  want  to 

use . . . " 

DPRINT  "+-*/"<  >..."; 

DWHILE  CHAR-""  DO 

DRUM  INKEYCCHAR) 

DENDWHILE 

jPRINT 

DFLAG-SUBSTRC CHAR, LOOKUP  J 

CON  FLAG  GOTO  10,20,30,40,50,60,70 

10  PRINT  FIRST*SECOND  \  GOTO  1 

20  PRINT  FIRST-SECOND  \  GOTO  1 

30  PRINT  FIRST*SECOND  \  GOTO  1 

40  PRINT  FIRST/SECOND  \  GOTO  1 

50  PRINT  FIRSTASECOND  \  GOTO  1 

60  PRINT  F1RST<SECDND  \  GOTO  1 

70  PRINT  FIRST>SECOND  \  GOTO  1 

100  PRINT  "Procedure  Terminated  Due  to  0 


I nput . 
jEND 
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1JN rUI     Get  data  from  a  device  path 


Syntax:      INPUT  Wpath,]  [prompt,]  variable  [,  variable.,.] 


Function:  INPUT  accepts  input  from  the  specified  path.  (The 
default  is  the  keyboard.)  When  a  procedure  encounters 
INPUT,  it  displays  a  question  mark  and  awaits  data  from  the 
specified  path.  If  you  provide  a  string  type  prompt  for  INPUT, 
it  displays  the  text  of  the  prompt,  rather  than  a  question 
mark. 

INPUT  stores  the  data  it  collects  in  the  variable  you  specify. 
The  type  of  the  receiving  variable  must  match  the  type  of 
data  received. 

Because  INPUT  sends  data  (the  question  mark  prompt  or  the 
user-specified  string  prompt),  it  is  really  both  an  input  and  an 
output  statement.  This  means  that,  if  you  use  a  path  other 
than  the  standard  input  path,  you  should  not  use  the 
UPDATE  mode.  If  you  do,  the  prompts  produced  by  INPUT 
write  to  the  file  specified  by  the  path  number. 

If  the  data  received  does  not  match  the  type  of  data  INPUT 
expects,  it  displays  the  message: 

••INPUT  ERROR  -  RETYPE** 

followed  by  a  new  prompt.  "You  must  then  enter  the  entire 
input  line,  of  the  correct  type,  to  satisfy  INPUT,  For  more 
information,  see  GET. 
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Parameters: 

path  Either  a  variable  containing  the  path  number, 

or  the  absolute  path  number  to  the  file  or 
device  from  which  you  want  to  receive  input.  If 
you  want  to  receive  input  from  the  keyboard, 
do  not  include  a  path  number. 

prompt  Text  you  type  as  a  message  to  be  displayed 

when  BASIC09  executes  an  INPUT  statement. 

variable  The  variable  name  in  which  you  want  to  store 

the  data  received  by  INPUT.  The  type  of  vari- 
able must  match  the  type  of  input. 

Examples: 

INPUT  NUMBER ,NAME$, LOCATION 

INPUT  #PATH,X,Y,Z 

INPUT  "What  is  your  selection:  "jCHDICE 

INPUT  #HQST, "What's  your  ID  number?  ",IDNUM 


Sample  Program: 

This  procedure  calculates  the  day  of  the  week  for  a  specified 
date.  It  asks  you  for  the  date  using  the  INPUT  command. 

PRDCEDURE  weekday 

DDIM  X,Y,D,M,CALC: INTEGER;  DAY,M0NTK:STRING[2] ; 

YEAR:STRINGE4];  WEEKDAY  C7): STRINGI93 

IDIM  ANUM,BNUM,CNUM,DNUM,ENUM,FNUM,GNUM,NNUM, 

INUM: INTEGER 

CPRINT  USING  "S80  "."Day  of  the  Week  Program" ,"For 

any  year  after  1752" 

CPRINT 

DPRINT  "Enter  doy  Ce.g.  08):  ";   \  INPUT  DAY 

DPRINT  "   Enter  month  (e.g.  12):  "j   \  INPUT  MONTH 

DPRINT  "   Enter  year  (e.g.  1986):  ";   \  INPUT  YEAR 

DY=VAL(YEAR)  \M=VAL<MONTH>  \D-VAL(DAY> 

QFOR  X-1  TO  7 

OREAD  WEEKDAYCX) 

GNEXT  X 

:anum=int(.6*i/m> 

jBNUM-Y-ANUM 
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0CNUM=M+12*ANUM 

DDNUM-BNUM/1 00 

DENUM-INTCDNUM/4) 

DFNUM-INTCDNUM) 

DGNUM-INTC5»BNUM/4) 

DHNUM«INT(13»tCNUM*1  )/5) 

DINUM=HNUM+GNUM-FNUM*ENUM+D-1 

DINUM-INUM-7*INT«INUM/7)+1 

DPR  I  NT 

DPR  INT   "The   cloy   of    the   week    on   "5    M;    "/";    D; 

../...    Y.    ..    ls......    WEEKDAY    (INUM) 

DDATfl    "Su nday", "Mo ndey" ."Tuesday",' 'Wednesday", 
"Thu  r  a day" , "Fr 1  day" , "So  t  u  rday" 

QEND 
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J..N  1     Convert  real  number  to  whole  number 


Syntax:      INT(  value) 

Function:  Converts  a  real  number  to  a  whole  number  by  trun- 
cating any  fractional  part  of  the  real  number. 

Parameters: 

value  Any  negative  or  positive  real  number. 

Examples: 

PRINT  INT<77.89) 
PRINT  INTCNUM) 
PRINT  INT<-8.12) 

Sample  Program: 

The  RND  function  produces  real  numbers.  This  procedure  uses 
INT  to  convert  the  real  RND  output  to  integer  values. 

PROCEDURE    integer 
DDIM  T:INTEGER 
CFOR   T-1    TO    19 
3R=RND(S0)-25 
QPRINT   R.INTCR) 
UNEXT   T 
DEND 
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x\l  I  j  I  j    Remove  a  procedure  from  memory 


Syntax:       KILL  procedure 


Function:  Unlinks  (removes)  an  external  procedure  from  the 
BASIC09  procedure  directory.  If  the  procedure  is  not  external, 
but  resides  in  BASIC09's  workspace,  KILL  has  no  effect. 

Use  KILL  to  remove  auto-loaded  (packed)  procedures  that  are 
called  by  RUN  or  CHAIN.  You  can  also  use  KILL  with  auto- 
loading procedures  as  a  method  to  overlay  programs  within 
BASIC09. 

Warning:  Be  certain  you  do  not  KILL  an  active  proce- 
dure. Also  be  certain  that  when  you  use  RUN  and  KILL 
together,  that  both  statements  use  the  same  string  vari- 
able that  contains  the  name  of  the  procedure  to  RUN 
and  KILL. 


Parameters: 

procedure 


The  name  of  the  external  procedure  you  want 
to  KILL.  Procedure  can  either  be  a  name  or  a 
variable  containing  the  procedure  name. 


Examples: 


PROCEDURENAME*  -  "AVERAGE" 
RUN  PROCEDURENAME* 
KILL  PROCEDURENAME* 

INPUT  "Which  teat  do  you  want  to  run?  ".TEST* 
RUN  TEST* 
KILL  TEST* 
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Sample  Program: 

This  procedure  calls  a  procedure  named  Show  to  display  ASCII 
values  on  the  screen.  When  it  no  longer  needs  the  Show  proce- 
dure, it  removes  Show  from  memory  using  KILL. 

PROCEDURE  produce 

J>IM  T,U: INTEGER 

DDJM  NUM.NUM1  , NUM2, TABLE, PROCNAME: STRING 

DPROCNAME-SHOW 

DTABLE-"1 23456789ABCDEF" 

DFOR  T=8  TO  IS 

DFDR  U-1   TO  15 

DNUM1-MIDSCTA8LE,T,1) 

QNUM2*MI D$( TABLE, U,1) 

DNUM=NUM1 +NUM2       (t  parameter  to  pass  to  Show. 

QRUN  PROCNAME(NUM) 

QNEXT  U 

HEXT  T 

CK1LL  "PROCNAME"  (»  remove  Show  from  the  workspace. 

CEND 

PROCEDURE  SHOW 
GPARAM  NUM:STRING 
DSHELL  "DISPLAY  "tNUM 

DEND 
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XjAN  D    Returns  the  logical  AND  of  two  numbers 


Syntax:       LAND{MumI,numi5 


Function:  Performs  the  logical  AND  function  on  a  byte-  or 

integer-type  value.  The  operation  involves  a  bit-by-bit  logical 
AND  of  the  two  numbers  you  specify.  For  instance,  if  you 
LAND  5  and  6,  the  logic  is  like  this: 


Decimal  5  = 
Decimal  6  = 

Binary  0101 
Binary  0110 

0101 

AND  0110 

0100 

=  4  Decimal 

Parameters: 

numl 

A  byte-  or 

num2 

A  byte-  or 

Examples: 

PRINT   LANDC11 ,12) 
PRINT   LfiND($20,$FF) 

Sample  Program: 

The  following  procedure  asks  eight  questions  and  uses  the  eight 
bits  of  one  byte  (contained  in  the  variable  STORAGE)  to  indicate 
either  a  "yes"  or  "no"  answer.  If  the  answer  is  "yes,"  it  sets  a 
corresponding  bit  to  1.  If  the  answer  is  "no,"  it  sets  a  corre- 
sponding bit  to  0,  using  LAND.  This  procedure  operates  in  con- 
junction with  the  sample  program  for  LXDR. 
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PROCEDURE  questions 

DDIM  QUEST ION: STRING [61];  T: INTEGER;  X .STORAGE: BYTE 
/■-  ODIM  ANSWER: STRING!  15 

DM 

DFOR  T-1  TD  8 

OREAD  QUESTION 

DPRIHT  QUESTION;  "  IY/N)?  "j 

D5ET  H,  ANSWER 

DPR I NT 

GIF  ANSWER ■"y"  OR  ANSWER '"Y"  THEN 

OSTORAGE'lORtSTORAGE.X)  [•  OR  STORAGE  if  yes. 

DELSE 

DSTDRAGE «IAND( STORAGE .LNOTCX))  C<  LAND  STORAGE  with  NOT  value  if  no, 

DENDIF 

Qt'UZ 

DMEXT  T 

DRUN  summary? STORAGE) 

DEND 

DDATA  "Do  you  have  more  than  one  Color  Computer" 

DDATA  "Do  you  use  your  Color  Computer  for  games" 
^"v  DDATA  "Do  you  use  your  Color  Computer  for  word  processing" 

GDATA  "Do  you  use  your  Color  Computer  for  business  applications" 

GDATA  "Do  you  use  your  Color  Computer  at  home" 

GDATA  "Do  you  use  your  Color  Computer  at  the  office" 

GDATA  "Do  you  use  your  Color  Computer  more  than  two  hours  a  day" 

GDATA  "Do  you  share  your  Color  Computer  with  others" 
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LihiF  1     Returns  characters  from  the  left  portion 
of  a  string 


Syntax:      LEFT$(string,length) 

Function:  Ketums  the  specified  number  of  characters  from  the 
specified  string,  beginning  at  the  leftmost  character.  If  length 
is  the  same  as  or  greater  than  the  number  of  characters  in 

string,  then  LEFT$  returns  all  the  characters  in  the  string. 

Parameters: 

string  A  sequence  of  ASCII  characters  or  a  string 

variable  name, 

length  The  number  of  characters  you  want  to  access. 

Examples: 

PRINT  LEFT$<MHDTD0GM,3) 
PRINT  LEFT$CA$,6) 

Sample  Program: 

The  following  procedure  extracts  the  first  name  from  a  list  of  ten 
names  with  the  LEFT$  function. 

PROCEDURE  flrstname 

DDIM  NAMES:STRIN0;  FIRSTNAME: STR tNGM B 3 

DPR INT  "Here  are  the  first  names:" 

DFOR  M  TD  11 

DREAD  NAMES 

DPDINTER-SUBSTRC  ",  NAMES)  {'find  space  between  first  and  last  names. 

DFIR5TNAME'LEFT$(NAP1ES,PDINTER-1)  (♦  extract  first  name. 

QPRINT  FIRSTNAME  <»  print  first  name. 

JOT  T 

3END 

DDATA  "Joe  Blonski","Mlke  Marvel", "Hal  Sieemish'V'Fred  Laungly" 

QDATA  "Jane  Mistey'V'Wendy  Pas  ton"  ."Martha  Jp  s  ha  ng",,p  Jacqueline  Rivers" 

CDATA  "Susy  Reetmore", "Wilson  Creding" 
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LjEa  jN     Returns  the  length  of  a  string 


Syntax:      LEN(striag) 

Function:  Returns  the  number  of  characters  in  a  string. 

Counts  blanks  or  spaces  as  characters. 

Parameters: 

string  A  literal  string  or  a  variable  containing  string 

characters. 

Examples: 

PRINT  LENC"ABCDEFGHIJKLM"> 

PRINT  LEN<NAME$) 

NAMES  -  "JOE" 

ADDRESS$  -  "2244  LANCASTER" 

TOTALLEN  -  LEN(NAME*)+LENC ADDRESS$) 

Sample  Program: 

The  following  procedure  uses  LEN  to  determine  which  name  in  a 
list  is  longest, 

PROCEDURE  longnome 

DDIM  NAMES, LNM: STRING;  LONGEST, LENGTH: INTEGER 

DNAMES-""  \LNAME \LENGTH-8  \LQNGEST'« 

OfOR  T-1  TQ  18 

DREAD  NAMES 

LTLENGTH-LEN<  NAMES) 

GIF  LONGE  STRENGTH  THEN 

D.DN6EST- LENGTH 

CLNAME- NAMES 

CENDIF 

LNEXT  T 

UPRINT  "The  longest  name  is  "•,  LNAME;  "  with  ";  LONGEST;  "  characters." 

uEND 

CDATA  "Joe  Blonski'V'Milce  Marvel", "Hal  SkeBmish", "Fred  Laungly" 

IDATA  "Jane  Misty"  ."Wendy  Pas  ton",  "Mart  ha  Upshong",  "Jacqueline  Rivers" 

IDATA  "Susy  Reetmore", ''Wilson  Creding" 
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LjEj  1     Assigns  a  variable's  value 


Syntax:      [LET]  variable  =  expression 


Function:  Assigns  a  value  to  a  variable.  BASIC09  does  not 
require  the  LET  statement  to  assign  values  but  does  accept  it 
in  order  to  be  compatible  with  versions  of  BASIC  that  do 
require  it. 

Parameters: 

variable  The  variable  to  which  you  want  to  assign  a 

value. 

expression         Either  a  numeric  or  string  constant  or  a 
numeric  or  string  expression. 


Notes: 


The  result  of  the  LET  expression  must  be  of  the  same  type 
as,  or  compatible  with,  the  variable  in  which  it  is  stored. 

BASIC09's  assignment  function  accepts  either  =  or  :=  as 
assignment  operators.  The  :=  form  helps  to  distinguish 
assignment  operations  from  comparisons  (test  for  equality) 
and  is  compatible  with  Pascal  programming. 

Use  BASIC09's  assignment  function  to  copy  entire  arrays  or 
complex  data  structures  to  another  array  or  complex  data 
structure.  The  data  structures  do  not  need  to  be  of  the 
same  type  or  shape,  but  the  size  of  the  destination  struc- 
ture must  be  the  same  as  or  larger  than  the  source  struc- 
ture. This  means  the  assignment  function  can  perform 
unusual  type  conversions.  For  example,  you  can  copy  a 
string  variable  of  80  characters  into  a  one-dimensional 
array  of  80  bytes. 
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Examples: 

LET   A    =    B 

LET    A    :-    B 

ANSWER    -    A    *    B 

LET    NAME$    :-    "JOE" 

NAME    $    •    FIRSTNAME*    +    "    "    +    LASTNAME$ 

Sample  Program: 

This  procedure  uses  LET  to  assign  a  random  value  to  the  vari- 
able R. 

PROCEDURE    getint 
DDIM   T: INTEGER 
LTDR   T-1    TO    10 
DLET   R-RND(50>-25 
DPRINT   R,INT(R> 
DNEXT   T 
DEND 
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.Li.NO  1     Performs  a  logical  NOT  on  a  number 


Syntax:      LNOT(vaiue) 


Function:  Performs  the  logical  NOT  function  on  an  integer  or 
byte  type  number,  The  operation  involves  a  bit-by-bit  logical 
complement  operation  of  the  number  you  specify.  For  instance, 
if  value  is  188,  the  logic  looks  like  this: 

188  Decimal  =  10111100  Binary 

NOT  10111100 
=  01000011 

01000011  Binary  =  67  Decimal 

LNOT  changes  each  bit  in  a  binary  number  to  its  complemen- 
tary binary  value — all  1  values  become  0  and  all  0  values 
become  1.  LNOT  returns  an  integer  result;  it  is  not  a  Boolean 
operator. 

Parameters: 

value  Any  decimal  or  hexadecimal  integer  or  byte 

number.  Precede  hexadecimal  numbers  with  $. 

Examples: 

PRINT  LNDTC88) 
A  -  LN0TCB) 
A  =  LN0T(*44> 

Sample  Program: 

This  procedure  uses  one  byte  (contained  in  the  variable  STOR- 
AGE) to  indicate  the  results  of  eight  questions.  Each  bit  in  the 
byte  indicates  a  Yes  or  No  answer  ("Yes  =  1  and  No  =  0).  The  com- 
bination logic  of  LAND  and  LNOT  masks  the  byte  X  so  that  it 
affects  only  the  appropriate  bit  of  STORAGE  to  set  it  to  0  if  the 
answer  is  No.  LOR  sets  the  appropriate  bit  to  1  if  the  answer  is 
Yes.  The  procedure  operates  in  conjunction  with  the  LXOR  sam- 
ple program. 
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PROCEDURE  questions 

DIM  fiUESTI0N:STR!N&(6i);  T: INTEGER;  X, STORAGE: BYTE 

DDIP1  ANSWER:  STRING!  1) 

nx=i 

DFOR  T-1  TO  8 

DREAD  QUESTIDN 

DPRINT  QUESTION;  "  it  mi  "s 

DGET  H,  ANSWER 

DPRINT 

HIF  ANSWER 'ttf  OR  ANSWER'"V"  THEN 

I]STORAGE-LORCSTQRAGE,»  (»  Answer  is  yes,  set  bit  to  1. 

:else 

CSTORAGE=lAND(STORAGE,LNOT<X»  («  Answer  is  no,  set  bit  US. 

DENDIF 

DX-X«2 

DNEST  T 

DPRINT  STORAGE 

DRUN  summary (STORAGE) 

lEND 

DDATA  "Do  you  have  wore  than  one  Color  Computer" 

DDATA  "Do  you  use  your  Color  Computer  for  games" 

DDATA  "Do  you  use  your  Color  Computer  for  word  processing" 

DDATA  "Do  you  use  your  Color  Computer  for  business  applications" 

IDATA  "Do  you  use  your  Color  Computer  at  home" 

jDATA  "Do  you  use  your  Color  Computer  at  the  office" 

DDATA  "Do  you  use  your  Color  Computer  more  than  two  hours  a  day" 

DDATA  "Do  you  share  your  Color  Computer  with  others" 
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JLOljr    Returns  natural  logarithm 


Syntax:      LOG(number) 

Function:  Computes  the  natural  logarithm  of  a  number  that 
is  greater  than  zero.  BASIC09  returns  the  logarithm  as  a  real 
type  result. 

Parameters: 

number  Any  integer,  byte,  or  real  number, 

Examples: 

PRINT  L00(3. 14159) 
LQGVALUE  =  L0G(88/PI) 

Sample  Program: 

This  procedure  calculates  the  natural  log  and  the  tog  to  base  10 
of  the  values  1-7. 

PROCEDURE  logs 

DDIM  NUM. T: INTEGER 

DFDR  T-1  TO  7 

DPRINT  "The  LOG  of  ";  T;  "  to  the  natural  base  * 

";  L0G(T> 

DPRINT  "The  LOG  of  ";  T;  "  to  base  19  -  "; 

LOG10(TJ 

DPRINT 

DNEXT  T 

DEND 
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JLt_/(jrlU    Returns  base  10  logarithm 


Syntax:      LOGlO(number) 

Function:  Calculates  the  base  10  logarithm  of  a  number. 
BASIC09  returns  the  logarithm  as  a  real  number, 

Parameters: 

number  Any  byte,  integer,  or  real  value. 

Examples: 

PRINT   LOG10($45> 
PRINT   LOG10(A> 
PRINT   LQG10<A/12> 

Sample  Program: 

This  procedure  calculates  the  natural  log  and  the  log  to  base  10 
of  the  values  1-7. 

PROCEDURE  logs 

CDIM  NUM.T: INTEGER 

CFOR  T-1  TO  7 

CPRINT  "The  LOG  of  ";  T;  "  to  the  natural  base  - 

"i  LOG(T) 

GPRINT   "The   LOG   of    ";    T;    "    to    base    10    »    "; 

LDG1 0(T> 

CPRINT 

DNEXT   T 

DEND 
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LOOP/ENDLOOP 

Establishes/Closes  a  loop 


Syntax:      LOOP 

statements) 
ENDLOOP 


Function:  Establishes  a  loop  in  which  you  can  install  EXITIF 
tests  at  any  location.  The  LOOP  and  ENDLOOP  statements 
define  the  body  of  the  loop,  EXITIF  tests  for  a  condition 
which,  if  TRUE,  causes  alternate  actions,  the  transfer  of  pro- 
cedure execution  to  another  routine,  or  both. 

If  you  do  not  include  an  EXITIF  statement,  the  loop  cannot 
terminate. 

Parameters: 

statements)       One  or  more  procedure  lines  to  execute  within 
the  loop. 

Examples: 

LOOP 

COUNT  •  COUNT+1 

EXITIF  CDUNT  >  100  THEN 

DONE  -  TRUE 

ENDEXIT 

PRINT  COUNT 

X-CDUNT/2 

ENDLOOP 

INPUT  X,Y 

LOOP 

PRINT 

EXITIF  X<0  THEN 

PRINT  "X  became  0  first" 

END 

ENDEXIT 

X  =  X-1 

EXITIF  Y-0  THEN 

PRINT  "Y  become  0  first" 
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END 

ENDEXIT 

Y-Y-1 

ENDLDOP 

Sample  Program: 

This  procedure  simulates  a  gambling  machine  that  awards  cash 
returns  depending  on  a  random  selection  of  kinds  of  fruits.  %u 
begin  with  a  stake  of  $25  and  win  or  lose  according  to  random 
selections  of  the  procedure. 

The  program  uses  LOOP/ENDLOOP  to  keep  operating  until  you 
run  out  of  cash. 

PROCEDURE  bandit 

CDIM  FRU1T1 , FRUITS, FRUIT3, STAKE: INTEGER; 

FRUIT<10>:STRING£6] 

DSTAKE-25 

DPRINT   \  PRINT  "You  have  $";  STAKE;  "  to  play 

with." 

3F0R  T  =  1  TO  10 

DREAD  FRUIT(T) 

DNEXT  T 

QLOOP 

DFRUIT1«RNDC9>+1  \FRU IT2=RND(9>*1  \FRUIT3-RND<9>+1 

DPRINT  FRUITCFRUITD;  "  ";  FRUITCFRUI T2> ;  "  "; 

FRUIT<FRUIT3> 

DIF  FRUIT(FRUIT1>=FRUITCFRUIT2)  AND  FRUITCFRUIT1 )- 

FRUIT<FRUIT3)  THEN 

DSTAKE-STAKE+10 

QELSE 

DIF  FRUIT(FRUIT1>-FRUIT<FRUIT2>  OR  FRUITCFRUIT2)- 

FRUIT<FRUIT3>  THEN 

DSTAKE*STAKE*2 

DELSE 

DIF  FRUIT(FRUIT1>-FRUIT(FRUIT3)  THEN 

DSTAKE-STAKE*1 

DELSE  STAKE-STAKE-1 

GENDIF 

DENDIF 

3ENDIF 

"EXITIF  STAKE<1  THEN 

ZPRINT 

IPRINT  "You're  Busted .. .Bet ter  go  home." 
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PROCEDURE  questions 

jDIM  QUESTIQN:STRINGC60] ;  T: INTEGER; 

X, STORAGE: BYTE 

ODIM  ANSWER:STRING[1 J 

jX-1 

jFOR  T-1  TD  8 

3READ  QUESTIDN 

GPRINT  QUESTIDN;  "  <Y/N>?  "; 

GGET  #0,ANSWER 

GPRINT 

GIF  ANSWER-"y"  DR  ANSWER-"Y"  THEN 

QSTORAGE-LORC STORAGE, X) 

DELSE 

aSTORAGE-LAND(STORAGE,LNOT(X)) 

GENDIF 

GX=X«2 

ONEXT  T 

GPRINT  STORAGE 

GRUN  summary(STORAGE) 

GEND 

QDATA  "Do  you  have  more  than  one  Color  Computer" 

QDATA  "Do  you  use  your  Color  Computer  for  games" 

QDATA  "Do  you  use  your  Color  Computer  for  word 

process  i  ng" 

QDATA  "Do  you  use  your  Color  Computer  for  business 

appl lent  ions" 

GDATA  "Do  you  use  your  Color  Computer  at  home" 

CDATA  "Do  you  use  your  Color  Computer  at  the 

office" 

DDATA  "Do  you  use  your  Color  Computer  more  than 

two  hours  a  day" 

QDATA  "Do  you  share  your  Color  Computer  with 


others' 
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Li XOiV    Returns  logical  XOR  of  two  numbers 


Syntax:      LXOR(  valuel,value2) 


Function:  Performs  the  logical  XOR  function  on  two-byte,  or 
integer-type,  values.  For  instance,  if  you  LXOR  the  numbers  5 
and  6  the  logic  is  like  this: 

Decimal  5  =  Binary  0101 
Decimal  6  =  Binary  0110 

0101 
LXOR   0110 


0011    =  3  Decimal 

If  one  bit  or  the  other  bit  in  the  evaluation  is  1,  but  not  both, 
LXOR  returns  a  result  of  1.  Otherwise,  LXOR  returns  a 
result  of  0. 

Parameters: 

wluel  A  byte  or  integer  number, 

value2  A  byte  or  integer  number. 

Examples: 

PRINT  LX0RC11 ,12) 
PRINT  LXQRC$20,$FF> 

Sample  Program: 

The  following  program  summarizes  the  results  of  the  sample 
program  for  LOR.  The  LOR  program  stored  the  answers  to  eight 
questions  in  a  single  byte.  This  procedure  reads  the  byte  and 
displays  appropriate  comments.  LXOR  checks  to  see  if  two  of  the 
answers  are  "yes"  or  "no." 
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DENDEXIT 

QPRINT  "Your  stake  is  now  $";  STAKE;  "." 

QPRINT 
DPRINT 
DINPUT  "Press  ENTER  to  pull  ogain...",Z* 

QENDLDQP 
QEND 

QDATA  "ORANGE", "APPLE",  "CHERRY", "LEMON", "BAN AN A" 
QDATA  "PEAR", "PLUM", "PEACH", "GRAPE", "APR  I  COT" 
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L* Orv    Returns  logical  OR  of  two  numbers 


Syntax:      L0R(valuel,value2) 


Function:  Performs  the  logical  OR  function  on  a  byte-  or 

integer-type  value.  The  operation  involves  a  bit-by-bit  logical 
OR  operation  on  two  values.  R>r  instance,  if  you  LOR  the 
numbers  5  and  6,  the  logic  is  like  this: 

Decimal  5  =  Binary  0101 
Decimal  6  =  Binary  0110 

0101 

OR    0110 


=      0111    =  7  Decimal 

If  one  bit  or  the  other  bit  is  1,  LOR  returns  a  result  of  1. 

Otherwise,  LOR  returns  a  result  of  0. 

Parameters: 

valuel  A  byte  or  integer  number. 

value2  A  byte  or  integer  number. 

Examples: 

PRINT   LDR(1 1,12) 
PRINT   LOR($20,$FF) 

Sample  Program: 

This  procedure  stores  the  answers  to  eight  "yes"  or  "no"  ques- 
tions in  one  byte,  named  STORAGE.  If  you  answer  "yes"  to  a 
prompt,  the  procedure  sets  a  corresponding  bit  to  1.  If  you 
answer  "no"  to  a  prompt,  the  procedure  sets  a  corresponding  bit 
to  0.  The  procedure  uses  LOR  to  set  bits  to  1  by  masking  all  bits 
except  the  one  it  needs  to  set.  The  procedure  operates  in  con- 
junction with  the  LXOR  sample  program. 
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PROCEDURE  summary 

DDIM  T: INTEGER;  A ,B , X ,TEST ,TEST2 ! BYTE ;  SUMMARY: 

STRINGCS01 

DPARAM  STORAGE: BYTE 

DA  =  0  \B=0 

DPRINT   \  PRINT 

DPRINT  "The  following  15  a  summary  of  the 

questionnaire  answers:" 

DPRINT 

UPRINT  "The  surveyee:  " 

DX-1 

DFOR  T-1  TO  8 

DTEST-LANDCSTORAGE , X> 

DREAD   SUMMARY 

DIF    TEST>0    THEN 

DPRINT    TAB(1 0);    SUMMARY 

CENDIF 

DX*X»2 

DNEXT    T 

DIF    LAND<STORAGE,128)>0   THEN 

DA-1 

OENDIF 

DIF    LAND<STORAGE,64>>0   THEN 

DB*1 

DENDIF 

DTEST2=LX0R<A,B) 

DIF  TEST2-1  THEN 

DPRINT  "This  computer  owner  either  uses  the 

computer" 

DPRINT  "more  than  two  hours  a  day  or  shares  it 

with  others." 

DPRINT  "This  is  a  heavy  use  situation." 

DENDIF 

DTEST2=LAND(A,B) 

DIF  TEST2=1  THEN 

QPRINT  "This  computer  user  uses  the  computer  more 

than  two" 

DPRINT  "hours  per  day  and  shares  it  with  others. 

This  is  a" 

GPRINT  "super  heavy  use  situation." 

DENDIF 

DEND 

CDATA  "Uses  more  than  one  computer" 

DDATA  "Plays  games" 
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GDATA  "Uses  the  computer  for  word  processing" 

DDATA  "Uses  the  computer  for  business" 

/"'••      DDATA  "Keeps  a  Color  Computer  at  home" 

DDATA  "Keeps  a  Color  Computer  at  the  office" 

DDATA  "Uses  the  computer  more  than  two  hours  a 

day" 

DDATA  "Shares  the  computer  with  others" 
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JVlIlJtJ)    Returns  characters  from  within  a  string 


Syntax:       MID$(.string,begin,length) 

Function:  Returns  a  substring  length  characters  long,  begin- 
ning at  begin.  Use  MID$  to  "take  apart"  a  string  consisting 
of  a  number  of  elements. 

Parameters: 

string  A  sequence  of  string  type  characters  or  a 

string  type  variable. 

begin  The  position  (an  integer  value)  in  string  of  the 

first  character  to  retrieve. 

length  The  number  of  characters  you  want  to  retrieve. 

Examples: 

NAME*  =  "JONES,  JGHN  M." 
LASTNAMES  -  MID$CNAME$ ,8 ,6) 
FIRSTNAME*  -  MI D* (NAMES , 1 , 5) 
INITIAL*  =  MID$CNAME$,15,2) 

Sample  Program: 

This  procedure  reverses  a  word  or  phrase  you  type.  MID$  reads 
each  character  in  your  phrase  from  the  end  to  the  beginning. 

PROCEDURE  reverse 

DDIM  PHRASE:STRING;  T ,BEGI N : I NTEGER 

DPRINT  "Type  a  word  or  phrase  you  want  to 

reverse : " ; 

DPRINT 

DINPUT  PHRASE 

OBEGIN=LEN<PHRASE) 

DPRINT  "This  is  how  your  phrase  looks  backwards:" 

DFOR  T-BEGIN  TO  1  STEP  -1 

DPRINT  MID$CPHRASE,T,1 ); 

DNEXT  T 

DPRINT 

DEND 
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IVIOU    Returns  modulus  of  a  division 


Syntax:       MOD(mimberl,number2) 

Function:  Returns  the  modulus  (remainder)  of  a  division. 
MOD  divides  numberl  by  number2  and  calculates  the  remain- 
der. "You  can  use  MOD  to  put  a  limit  on  a  numeric  variable. 
For  instance,  regardless  of  the  value  of  X,  MOD(X,3)  produces 
numbers  only  in  the  range  0  through  2.  MOD(X,5)  produces 
numbers  only  in  the  range  of  0  through  4. 

"You  can  use  MOD  to  cause  repeating  sequences.  For  instance, 
in  a  loop,  MOD(X,3)  produces  a  repeating  sequence  of  0,  1,  2, 
where  X  increases  by  1  in  each  step  of  the  loop. 

Parameters: 

numberl  A  byte,  integer  or  real  number  dividend. 

number2  A  byte,  integer  or  real  number  divisor. 

Examples: 

PRINT  M0D<99,5> 


11-93 


BASIC09  Reference 


Sample  Program: 

This  procedure  uses  MOD  to  execute  repeatedly  routines  that 
display  asterisks  on  the  screen.  There  are  eight  subroutines  that 
the  MOD  function  selects  over  and  over  through  100  passes. 

PROCEDURE    stardown 

DDIM   T: INTEGER 

DSHELL   "TMODE    -PAUSE" 

DFOR   T-1    TO    100 

DON   M0D(T,8)+1    GOSUB    10,20,30,40,50,50,70,80 

QNEXT   T 


DSHELL  "TMODE  PAUSE" 

CEND 

10DPRINT  USING 

"S1 0*" 

■•  ► l- 

RETURN 

20DPRINT  USING 

"S10*" 

■•int-1 

'  \  RETURN 

30DPRINT  USING 

"S10"" 

"»  *  1 

"  \  RETURN 

4  0DPRINT  USING 

"S10A" 

"  1 1 1 

•"  \  RETURN 

50QPRINT  USING 

"SH»" 

■■ «  •  1 

**"  \  RETURN 

60GPRINT  USING 

"S1 0*" 

11 #  *  < 

*"  \  RETURN 

70CPRINT  USING 

"S10*" 

11  *  *  1 

"  \  RETURN 

80DPRINT  USING 

"S1 0«" 

" *  *' 

'  \  RETURN 

DEND 
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-N.fcjX  1     Causes  repetition  in  a  FOR  loop 


Syntax:       FOR  variable  =  init  val  TO  end  val  [STEP 
value] 

[procedure  statements] 
NEXT  variable 

Function:  NEXT  forms  the  bottom  end  of  a  FOR/NEXT  loop. 

Any  program  statements  between  FOR  and  NEXT  are  exe- 
cuted once  for  each  repetition  of  the  loop,  from  the  initial 
value  to  end  value. 

Parameters: 

variable  Any  legal  numeric  variable  name. 

init  val  Any  numeric  constant  or  variable. 

end  val  Any  numeric  constant  or  variable. 

value  Any  numeric  constant  or  variable. 

procedure  Procedure  lines  you  want  to  execute  within 

statements  the  loop. 

For  more  information,  see  FOR/NEXT/STEP. 
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.NO  1     Returns  the  complement  of  a  value 


Syntax:      NOT<  va/ue) 

Function:  Returns  the  logical  complement  of  a  Boolean  value 
or  expression. 

Parameters: 

value  A  Boolean  value  (True  or  False),  or  an  expres- 

sion resulting  in  a  Boolean  value. 

Examples: 

DIM  TEST:BDQIEAN 
WHILE  NOT(TEST)  DD 

A  =  A  +  1 
TEST=A=B 

ENDWHILE 

Sample  Program: 

This  procedure  redirects  the  current  directory  listing  to  a  file 
named  Dirfile.  It  then  opens  Dirfile  and  reads  the  contents,  dis- 
playing each  line  on  the  screen.  It  uses  NOT  in  a  WHILE/END- 
WHILE  loop  to  make  sure  that  the  end  of  the  file  has  not  been 
reached  before  trying  to  read  another  entry. 

PROCEDURE  read-file 

IDIM  A:STRING[80] 

CDIM  PATH:BYTE 

CSHELL  "DIR  >  dirfile" 

DDPEN  #PATH,"dirf ile":READ 

DWHILE  NDT  EDFC#PATH>  DO 

DREAD  *PATH,A 

DPRINT  A 

DENDWHILE 

DCLOSE  #PATH 

QEND 
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ON  ERROR/GOTO 

Establishes  an  error  trap 

Syntax:       ON  ERROR  [GOTO  linenum] 

Function:  Sets  an  error  trap  that  transfers  control  to  the  spec- 
ified line  number  in  a  procedure.  This  lets  your  program 
recover  from  an  error  and  continue  execution.  To  use  these 
commands,  your  program  must  have  at  least  one  numbered 
fine — the  line  to  bi-anch  to  in  the  event  of  an  error. 

Parameters: 

linenum  The  line  to  which  you  want  BASIC09  to 

branch  should  an  error  occur. 

Notes: 

•  ON  ERROR  GOTO  is  effective  only  with  non-fatal,  run- 
time errors.  If  such  an  error  occurs  without  a  preceding  ON 
ERROR  GOTO  statement,  BASIC09  enters  the  DEBUG 
mode.  You  must  specify  ON  ERROR  GOTO  before  an  error 
occurs. 

You  turn  on  error  trapping  by  specifying  ON  ERROR 
GOTO  linenum.  You  turn  off  error  trapping  by  specifying 
ON  ERROR  without  a  line  number. 

Use  ON  ERROR  GOTO  with  the  ERR  function  (that 
returns  the  code  of  the  last  error)  to  specify  a  particular 
action  for  a  particular  error.  You  can  also  use  ERROR  to 
simulate  an  error  to  test  error  trapping.  For  more  informa- 
tion on  this,  see  ERROR. 


• 
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Examples: 

DDIM  FILENAME: STRING 
DDIM  PATH: INTEGER 

10GINPUT  "Name  of  file  to  create?  ".FILENAME 

DON  ERROR  GOTO  100 

GCREATE  *PATH, FILENAME: UPDATE 

DEND 

100DPRINT  "That  file  already  exist 5. .. please 

choose  another  name..." 

DGOTO  10 

DEND 

Sample  Program: 

If  you  created  a  directory  file  with  the  GET  sample  program, 
you  can  use  this  procedure  to  delete  files  from  the  original  direc- 
tory using  key  characters.  For  instance,  you  might  type  XX  as 
key  characters.  This  means  that  any  filename  containing  the 
character  group  XX  is  deleted.  %u  can  select  any  key  characters 
you  wish,  but  be  sure  they  apply  only  to  files  you  want  to 
delete. 

If  you  want  to  delete  all  the  files  in  the  directory,  type  an  aster- 
isk (*)  when  asked  for  key  characters. 

This  procedure  uses  ON  ERROR  to  let  the  procedure  continue, 
even  if  a  directory  entry  cannot  be  deleted — if  an  entry  is  a  sub- 
directory. Without  the  ON  ERROR  function,  the  procedure 
would  produce  an  error  and  cease  execution  when  it  tried  to 

delete  a  subdirectory. 

PROCEDURE  purge 

DREM  Use  caution  with  this  procedure 
DREM  Be  sure  to  specify  key  characters 
DREM  thot  exist  only  in  the  files  you 
GREM  wont  to  delete! 

ZDIM  PATH: INTEGER 
CDIM  NAMEC100):STRING 
DDIM  WILDCARD:STRING 

DX*0 

DOPEN    *PATH,"dirf ile":READ 
ZINHILE   NOT(EOFC#PATH))    DO 
CX  -  X  + 1 

DREAD   #PATH,NAMECX) 
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DENDWHILE 

OFOR   T-1    TD    X 

DPRINT    NAMECTJ, 

CNEXT   T 

GINPUT  "Wildcard  Characters  ..." .WILDCARD 

jFOR  T  =  1  TD  X 

HON  ERROR  GOTO  100 

HIF  SUBSTR<WILDCARD,NAME(T))>0  OR  WILDCARD 

THEN 

DPRINT   "DELETING   ";    NAMEtT);    "    " 

□DELETE    NAMECTJ 

□END  IF 

10DNEXT   T 

DEND 

100DPRINT   "*D«O*OERR0R,D"s    NAME(T);    "Dcannot    be 

deleted. . .continuing." 

DGOTO    1 0 

DEND 
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t_JlN  / IjtOO  U  Jj    Jumps  to  subroutine  on  a 

specified  condition 

Syntax:       ON  pos  GOSUB  lineman  [Jineman,..,] 

Function:  Transfers  procedure  control  to  the  line  number 
located  at  position  pos  in  the  list  of  line  numbers  immediately 
following  the  GOSUB  command.  For  example,  if  pos  equals  1, 
BASIC09  branches  to  the  first  line  number  it  encounters  in 
the  list.  If  pos  equals  2,  BASIC09  branches  to  the  second  line 
number  it  encounters  in  the  list.  If  pos  is  greater  than  the 
number  of  items  in  the  list,  execution  continues  with  the  next 
command  line.  To  use  ON/GOSUB  you  must  have  numbered 
lines  to  match  the  line  numbers  in  your  list.  End  the  routines 
accessed  by  ON/GOSUB  with  a  RETURN  statement. 

Parameters: 

pos  An  integer  value  pointing  to  a  line  number  in 

a  list  of  line  numbers. 

linenum  Any  numbered  line  in  the  procedure. 

Examples: 

PRINT  "You  can  now:  (1>  End  the  program  (2)  Print 

the  result  a" 

PRINT  "  <3>  Try  again        C4)  Start 

a  new  program" 

INPUT  "Type  the  letter  of  your  choice:  ".CHDICE 

ON  CHOICE  GOSUB  100,  200,  300,  400 
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10,20,30,40 ,50,60 ,70,80 


Sample  Program: 

This  procedure  uses  MOD  to  execute  repeatedly  a  sequence  of 
GOSUB  commands.  A  loop  of  index  of  80  causes  execution  to 
jump  to  each  line  number  in  the  list  10  times. 

PROCEDURE  repeat 

DSHELL  "TMODE  -PAUSE" 

DDIM  T: INTEGER 

QFOR  T-1  TO  80 

DON  M0D(T,8)+1  GOSUB 

GNEXT  T 

jSHELL  "TMDDE  PAUSE" 

jEND 

1 0DPRINT  USING  "S1 8A 

20GPRINT  USING  "S10* 

30DPRINT  USING  "S1 0* 

40DPRINT  USING  "S10" 

50CPRINT  USING  "S1B* 

60IIPRINT  USING  "S1 0* 

703PRINT  USING  "S1 0* 

80GPRINT  USING  "S10A 

GEND 


*"  \  RETURN 
**"  \  RETURN 
»»*"  \  RETURN 
**«»"  \  RETURN 
..*.«'•  \  RETURN 
.,«*'■  \  RETURN 
..*•■  \  RETURN 
«*"  \  RETURN 
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O-N/CtO  -I  \J    Jump  to  line  number  on  a 
specified  condition 


Syntax:       ON  pos  GOTO  linenum  [,/inenum,...] 


Function:  Transfers  procedure  control  to  the  line  number 
located  at  position  pos  in  the  list  of  line  numbers  immediately 
following  the  GOTO  command.  Fbr  example,  if  pos  equals  1, 
BASIC09  branches  to  the  first  line  number  it  encounters  in 
the  list.  If  pos  equals  2,  BASIC09  branches  to  the  second  line 
number  it  encounters  in  the  list.  If  pos  is  greater  than  the 
number  of  items  in  the  list,  execution  continues  with  the  next 
command  line.  To  use  ON/GOTO  you  must  have  numbered 
lines  to  match  the  line  numbers  in  the  list. 

Parameters: 

pos  An  integer  value  in  a  range  from  1  to  the 

number  of  items  in  the  list  following  GOTO. 

linenum  Any  numbered  line  in  the  procedure. 

Examples: 

PRINT   "You    can    now:    <1>    End    the   program   (2)    Print 

the    results" 

PRINT  "  C3)  Try  again        (4)  Start 

a  new  program" 

INPUT  "Type  the  letter  of  your  choice:  ", choice 

DN  CHOICE  GOTO  100,  200,  300,  400 

Sample  Program: 

This  procedure  converts  decimal  numbers  to  binary.  It  uses  ON 
GOTO  to  execute  the  operation  you  select  from  a  menu:  Convert 
a  number,  display  the  result  of  all  conversions,  or  end  the 
program. 

PROCEDURE  bicalc 

qd i  manumber,num:,x,  storage:  integer;abi  :  string; 
*arraycs0,2>:string 

c:count=0 
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1 0DBI -""  \NUMBER=0  \NUM=0  \X-0  \STQRAGE-0 

DINPUT  "Number  to  convert  to  binary  " , NUMBER 

□IF  NUMBER=0  THEN  END 

□ENDIF 

.IINUM  =  LOG10(  NUMBER)/.  3 

DNUM»2*NUM  \STORAGE=NUMBER 

CREPEAT 

GX-NUMBER/NUM 

□IF    X>0    THEN   BI -BI+"1 " 

□NUMBER =M0D( NUMBER ,NUM) 

HELSE   BI-BI+"0" 

CENDIF 

□NUM-NUM/2 

□UNTIL    NUM<=1 

□IF   NUMBER>0    THEN 

□BI=BI+"1" 

□ELSEABI-BI+"0" 

3ENDIF 

□PRINT  STORAGE;  "  -  ";  BI-,  "  In  binary." 

□PRINT 

□CDUNT=C0UNT+1 

DARRAYC CQUNT.1 )-STR$CSTORAGE> 

DARRAYCC0UNT,2)-BI 

123PRINT  "Do  you  want  to:  <1>  Convert  another 

number , " 

DPRiNT   "TrmTrrnnrrTTTlC 2 )   Display   all    calculations 

thus    far." 

CPRINT   "TTTTTTITTTTTTTnt 3 )    End    the   program." 

□INPUT   "Enter    1,    2,    or    3... ".choice 

□DN    choice   GOTO    10,20,30 

□END 

203FOR   T-1    TD    COUNT 

□PRINT   ARRAYCT.1);    ;    ARRAYCT.2) 

□NEXT   T 

□GOTO    12 

30DPRINT      \    PRINT   "   Program   Terminated" 

□END 
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C/-T  ii/JN     Opens  a  path  to  a  device 


Syntax:       OPEN  #path,"pathlisf  [access  mode][  + access 
mode][  +  ...] 


Function:  Opens  an  input/output  path  to  a  disk  file  or  to  a 
device.  When  you  open  a  file,  you  can  select  one  or  more  of  the 
following  access  modes: 


Mode 


Function 


READ 

WRITE 
UPDATE 

EXEC 
DIR 

Parameters: 

path 

pathlist 
access  mode 


Lets  you  read  (receive)  data  from  a  file  or 
device  but  does  not  allow  you  to  write  (send) 
data. 

Lets  you  write  data  to  a  file  or  device  but  does 
not  allow  you  to  read  data. 

Lets  you  both  read  from  and  write  to  a  file  or 
device. 

Specifies  that  the  file  you  want  to  access  is  in 
the  current  execution  directory. 

Specifies  that  the  file  you  want  to  access  is  a 
directory-type  file. 


The  variable  in  which  BASIC09  stores  the 
number  of  the  newly  opened  path. 

The  route  to  the  file  or  device  to  be  opened, 
including  the  filename  if  appropriate. 

The  type  of  access  the  system  is  to  allow  for 
the  file  or  device.  Use  a  plus  symbol  to  specify 
more  than  one  type  of  access. 
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Notes: 

•  The  access  mode  defines  the  direction  of  I/O  transfers. 

•  Because  OS-9  files  are  byte-addressed  and  are  unformat- 
ted, you  can  set  up  the  filing  system  you  want  for  a  partic- 
ular application.  Your  system  can  read  the  data  contained 
in  a  file  as  single  bytes  or  in  groups  of  any  size  you  want. 

•  You  can  expand  a  file  using  PRINT,  WRITE,  or  PUT  state- 
ments to  write  beyond  the  current  end-of-file. 

Examples: 

OPEN  #TRANS,  "transportation": UPDATE 
OPEN  #SPDDL,"/user4/report":WRITE 
OPEN  #GUTPATH,name$:UPDATE+EXEC 


Sample  Program: 

This  procedure  opens  a  path  to  both  the  SYS  directory  on  Drive 
/DO  and  the  error  message  file. 

PROCEDURE  readerr 

HDIM  A:STR1NGC80] 

EDIM  PATH:BYTE 

COPEN    *,PAThV,/D0/SYS/ERRItSG":READ 

DWHILE    EOF<*PATHX>TRUE   DO 

DREAD    #PATH,A 

DPR  I  NT    A 

DENDWHILE 

DCLOSE    'PATH 

DEND 
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XJMX    Performs  a  Boolean  OR  operation 


Syntax:       operandi  OR  operand2 

Function:  Performs  an  OR  operation  on  two  or  more  values, 
returning  a  Boolean  value  of  either  TRUE  or  FALSE. 

Parameters: 

operandi  Either  numeric  or  string  values, 

operand2 

Examples: 

PRINT  ft>3  OR  B>3 

PRINT   A$="YES"    or    B$="YES" 
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Sample  Program: 

This  procedure  asks  you  to  type  a  word  or  phrase,  then  converts 
all  lowercase  characters  to  uppercase.  It  uses  OR  to  test  for  a 
character  in  your  word  or  phrase  that  is  outside  of  the  ASCII 
values  for  lowercase  letters.  If  it  is,  the  character  does  not  need 
converting. 

PROCEDURE  uppercase 

lDIM  PHRASE,NEWSTRING:STRINGC80];  CHARACTER: 

5TRINGM  ]  j  T,X:  INTEGER 

DNEWSTRING \PHRASE 

DPRINT  "Type  a  phrase  In  lowercase  and  I  will  make 

it  uppercase." 

DINPUT  PHRASE 

DFOR  T-1  TD  LENCPHRASE) 

GCHARACTER«MID$(PHRASE,T,1  ) 

CX=ASC(CHARACTER) 

GIF  X<97  OR  X>122  THEN 

DNEWSTRING=NEWSTRING*CHARACTER 

CELSE 

CX=X-32 

DNEWSTRING-NEWSTRING+CHRJCX) 

OENDIF 

DNEXT  T 

CPHRASE-NEWSTRING 

CNEWSTRING-"" 

GPRINT    PHRASE 

jEND 
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ifAlxANL    Establishes  variables  to  receive  from 
another  procedure 


Syntax:      PARAM  variabH,...]htype][;variable]i>...][:type] 


Function:  Defines  the  parameters  that  a  called  procedure 
expects  to  receive  from  the  procedure  that  calls  it.  When 
using  PARAM,  be  sure  that  the  total  size  of  each  parameter 
in  the  calling  procedure's  RUN  statement  is  the  same  as  the 
defined  size  in  the  called  procedure's  PARAM  statement. 

Parameters: 

variable  A  simple  variable,  an  array  structure,  or  a 

complex  data  structure. 

type  Byte,  Integer,  Real,  Boolean,  String,  or  user 

defined. 

Notes: 

•  BASIC09  checks  the  size  of  each  parameter  to  prevent  acci- 
dental access  to  storage  other  than  that  assigned  to  the 
parameter.  However,  BASIC09  does  not  check  that  parame- 
ters are  of  the  proper  type.  In  most  cases  you  must  be  sure 
that  types  evaluated  in  RUN  statements  match  the  types 
defined  in  the  PARAM  statements. 

However,  because  BASIC09  does  not  perform  type  checking, 
it  is  possible  to  perform  useful  but  normally  illegal  type 
conversions  of  identically-sized  data  structures.  For  example, 
you  could  pass  a  string  of  80  characters  to  a  procedure 
expecting  a  byte  array  of  80  elements.  Each  character  in 
the  string  is  assigned  a  corresponding  position  in  the 
array. 

•  You  declare  simple  arrays  by  using  the  variable  name, 
without  a  subscript,  in  a  PARAM  statement. 
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•  You  can  declare  several  variables  of  the  same  type  by  sepa- 
rating them  with  commas.  To  separate  variables  of  differ- 
ent types,  follow  each  type  group  with  a  colon,  the  type 
name,  and  then  a  semicolon. 

•  If  you  do  not  include  a  maximum  length  for  a  string  vari- 
able enclosed  in  brackets  following  the  type,  like  this: 

DIM  name : str ing[251 

BASIC 09  uses  a  default  length  of  32  characters  for  strings, 
"You  can  declare  shorter  or  longer  lengths,  to  the  capacity  of 
BASIC09's  memory. 

•  Arrays  can  have  one,  two,  or  three  dimensions.  The 
PARAM  format  for  dimensioned  arrays  is  the  same  as  for 
simple  variables  except  you  must  follow  each  array  name 
with  a  subscript,  enclosed  in  parentheses,  to  indicate  its 
size.  The  maximum  array  size  is  32767. 

Arrays  can  be  either  of  the  standard  BASIC09  type,  or  of  a 
user-defined  type.  To  create  your  own  data  types  for  simple 
variables,  arrays,  and  complex  data  structures,  see  TYPE, 

Examples: 

PARAM  NUMBER; INTEGER 

PARAM  NAME:STRING[2S] ; ADDRESS : STR I NGt 30 ] ;2IP: 

INTEGER 

PARAM   N01 ,N02,N03:REAL;NQ4,N0S,ND6: INTEGER;N07: 
BYTE 

Sample  Program: 

The  first  procedure  asks  you  to  enter  a  decimal  number.  Then,  it 
asks  you  to  choose  whether  you  want  to  convert  the  number  to 
binary  or  hexadecimal.  Depending  on  your  choice,  the  procedure 
calls  (using  RUN)  either  a  procedure  named  Binary  or  a  proce- 
dure named  Hex,  It  passes  the  number  you  typed  to  the  appro- 
priate procedure  for  conversion. 
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PROCEDURE  convert 

ODIM  NUMBER, CHOICE: INTEGER 

CPRINT  USING  "S80*";  "Hexadecimal  -  Binary 

Conversion  Program" 

DPR  I  NT 

10DINPUT   "Number    to    conver t ...", NUMBER 

DIF    NUMBER-0    THEN 

DEND 

DENDIF 

DINPUT   "Choose:    (1)    Binary   or    (2)    Hex ...", CHOI CE 

DON    CHOICE   GOTO   20,30 

20ORUN    BINARY(NUMBER) 

DGDTD    10 

30CRUN    HEX(NUMBER) 

DGOTO    10 

DEND 

PROCEDURE  binary 

DDIM  NUM.X, STORAGE: INTEGER;  BIiSTRING; 

ARRAY(50,2>:STRING 
DPARAM  NUMBER: INTEGER 
DCDUNT-0 

DBI \NUM=0  \X-0  \STORAGE-0 

DNUM=LDG18(NUMBER)/.3 

DNUM-2"NUM  \STORAGE=NUMBER 

CREPEAT 

DX=NUMBER/NUM 

OIF  X>0  THEN 

0BI=BI+"1" 

DNUMBER=MOD( NUMBER, NUM> 

DELSE 

DBI=BI+"0" 

DENDIF 

DNUM=NUM/2 

CUNTIL  NUM<-1 

CIF  NUMBER>0  THEN 

GBI =BI +"1 " 

DELSE 

DBI«BI+"0" 

DENDIF 

DPRINT  STORAGE;  "  =  ";  BI;  "  in  binary." 

DPR  I  NT 

DEND 
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PROCEDURE  hex 

DDIM  NUM.X, STORAGE: INTEGER;  TABLE ,HX : STR  I  NG; 

ARRAY(S0,2):STRING 

OPARAM  NUMBER: INTEGER 

0TABLE  =  ,,1234SG?89ABCDEF" 

DHX-"M  \NUM=0  \X  =  0  \STORAGE-0 

DNUM-LOG10(NUMBER)/1 .2 

DNUM=16*NUM  \STORAGE=NUMBER 

DREPEAT 

IIX- NUMBER /NUM 

3IF  X>0  THEN 

ZIHX*HX  +  MID*(TABLE,X,1  ) 

DNUMBER-MQDt NUMBER, NUM> 

CELSE  HX=HX*"0" 

DENDIF 

DNUM-NUM/1S 

DUNTIL  NUM<-1 

DIP  NUMBER>0  THEN 

HHX-HX<-MID*{TABLE,  NUMBER,  1  ) 

DELSE 

DHX-HX*M0" 

DENDIF 

DPR  I  NT  STORAGE;  "  =  " ;  HX ;  "  in  hexadecimal." 

DPRINT 

DEND 
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x^AUfeJli     Suspends  execution  and  enters  Debug 


Syntax:      PAUSE  text 


Function:  Suspends  the  execution  of  a  procedure  and  causes 
BASIC09  to  enter  the  DEBUG  mode.  If  you  include  text  with 
the  PAUSE  command,  it  is  displayed  on  the  screen. 

Place  PAUSE  statements  in  a  program  temporarily  to  observe 
the  way  in  which  the  procedure  operates  and  to  track  down 
programming  errors.  When  the  procedure  is  opei-ating  cor- 
rectly, remove  the  PAUSE  statement. 

After  using  DEBUG,  you  can  continue  execution  of  the  paused 
procedure  with  the  CONT  command. 

Parameters: 

text  A  message  you  want  PAUSE  to  display  on  the 

screen  when  BASIC09  executes  the  statement. 

Examples: 

PAUSE 

PAUSE  The  array  is  now  full. 
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x  xLJjiXV    Returns  the  value  in  a  memory  location 


Syntax:      PEEK(mem) 


Function;  Returns  the  value  of  a  memory  byte  as  a  decimal 
integer.  The  value  returned  is  in  the  range  0  to  255,  PEEK  is 
the  complement  of  the  POKE  statement. 

See  also  ADDR. 

Parameters: 

mem  An  integer  value  representing  the  location  of 

the  memory  byte  you  want  to  examine.  The 
memory  byte  is  relative  to  the  current  pro- 
cess's address  space. 

Examples: 

PRINT  PEEKC15250) 

MEMVAL  =  PEEKC44S0) 
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Sample  Program: 

This  procedure  asks  you  to  type  a  phrase  in  uppercase  charac- 
ters. It  then  uses  ADDR  to  locate  the  area  in  memory  where 
BASIC09  stores  the  phrase.  Next,  it  reads  each  character  from 
memory  with  PEEK,  converts  it  to  lowercase  if  necessary,  and 
pokes  the  new  value  back  into  the  same  location.  When  the  pro- 
cedure displays  the  contents  of  the  phrase,  it  is  all  lowercase. 

PROCEDURE  lowercase 

GDIM  LDC.T: INTEGER;  PHRASE: STRINGC80 J 

QPRINT  "Type  a  phrase  in  UPPERCASE  and  I'll  make 

it  lowercase." 

□INPUT  PHRASE 

□LQC-ADDR(PHRASE) 

DFOR  T-LDC  TO  LOC+LENCPHRASE) 

□X=PEEKCT> 

OIF  X>32  AND  X<91  THEN 

□X-X+32 

DPOKE  T,X 

DENDIF 

DNEXT  T 

DPRINT  PHRASE 

DEND 
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rl    Returns  the  value  of  pi 

Syntax:      PI 

Function:  Returns  the  constant  value  3.14159265. 

Parameters:  None 

Examples: 

PRINT  "The  area  of  a  circle  with  a  radius  of  6 
inches  is  ";PI*6"2 

Sample  Program: 

This  procedure  uses  the  formula  (PI  +  2)/15  as  a  basis  for  calcu- 
lating a  screen  position.  Taking  the  sine  of  the  formula,  it  prints 
a  sine  wave  of  asterisks  down  the  screen. 

PROCEDURE  picalc 

DDIM  FORMULA, CALCULATE ,POSI Tl ON: REAL 

DSHELL  "DISPLAY  0C" 

QFDRMULA-<PI+2)/1S 

DCALCULATE=FORMULA 

DSHELL    "TMODE    -PAUSE" 

DFOR   T=8   TO    180 

GCALCULATE- CALCULATE +FORMUL A 

DPOSmON-iNT(SINCCALCULATE)*10  +  16> 

DPRINT   TABCPQSITION);    "•" 

CNEXT   T 

DSHELL  "TMODE  PAUSE" 

DEND 
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if  \Ji\.iL    Stores  a  value  in  a  memory  location 


Syntax:      POKE  mem,value 


Function:  Stores  a  value  at  the  specified  memory  address,  rel- 
ative to  the  current  process's  address  space.  Mem  is  an  abso- 
lute address  at  which  BASIC09  stores  a  byte  type  value. 
POKE  is  the  complement  of  the  PEEK  statement. 

'You  should  use  care  when  using  POKE.  Because  it  changes 
the  value  in  memory,  a  POKE  to  the  wrong  portion  of  memory 
could  cause  OS-9,  BASIC09,  or  your  procedures  to  malfunction 
until  you  reboot  the  system. 

See  also  ADDR. 

Parameters: 

mem  An  integer  value  representing  the  location  of 

the  memory  byte  you  want  to  change. 

value  The  value  to  store  in  the  specified  memory 

location. 

Examples: 

POKE    15250,13 
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Sample  Program: 

This  procedure  asks  you  to  type  a  phrase  in  uppercase  charac- 
ters. It  then  uses  ADDR  to  locate  the  area  in  memory  where 
BASIC09  stores  the  phrase.  Next,  it  reads  each  character  from 
memory,  converts  it  to  lowercase  if  necessary,  and  uses  POKE  to 
store  the  new  value  back  in  the  same  location.  When  the  proce- 
dure next  displays  the  contents  of  the  phrase,  it  is  all  lowercase. 

PROCEDURE  lowercase 

DDIM  LOC.T: INTEGER;  PHRASE :STRIKG[80 1 

DPRINT  "Type  a  phrase  In  UPPERCASE  and  I'll  make 

it  lowercase." 

□INPUT  PHRASE 

GLOC-ADDR(PHRASE) 

IFDR  T-LOC  TO  LOC+lEN<PHRAS£) 

□X=PEEK(T) 

□IF  X>32  AND  X<91  THEN 

IX-X+32 

OPDKE  T,X 

DENDIF 

□NEXT  T 

□PRINT   PHRASE 

□END 
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if  Ub    Returns  cursor's  column  position 


Syntax:      POS 

Function:  Returns  the  current  column  position  of  the  cursor. 

Parameters:  None 

Examples: 

PRINT   POS 

Sample  Program: 

This  procedure  is  a  simple  typing  program  that  uses  POS  to 
make  sure  that  words  are  not  split  when  you  type  to  the  end  of 
the  screen.  After  you  type  25  characters  on  a  line,  the  procedure 
breaks  the  line  at  the  next  space  character. 

PROCEDURE  wordwrap 

DDIM  CHARACTER:STRING[1 ] 

DPRINT  USING  "S32*";  "Word  Wrap  Program" 

DPRINT  USING  "S32*"j  "Press  [CTRLHC]  to  Exit" 

DPRINT 

QSHELL  "TMDDE  -ECHO" 
DWHILE  CHARACTERo"  "  DO 
DGET  #1 .CHARACTER 

DPRINT  CHARACTER; 

DIF  P0S>25  AND  CHARACTER-"  "  THEN 

DPRINT  CHR$(13) 

DENDIF 

DENDWHILE 

DSHELL  "TMODE  ECHO" 

DEND 
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PRINT    Displays  text 


Syntax:      PRINT  [#path]  [TAB(pos);]  data[;data...] 


Function:  Prints  numeric  or  string  data  on  the  video  display 
unless  another  path  is  specified. 

Parameters: 

path  The  number  corresponding  to  an  opened  device 

or  file.  If  you  do  not  specify  path,  the  default 
is  #1,  the  video  screen  (standard  output 
device).  To  print  to  another  device  or  file,  first 
OPEN  a  path  to  that  file  or  device  (see 
OPEN). 

pos  A  column  number  that  tells  TAB  where  to 

begin  printing.  Specify  any  number  from  0  to 
the  width  of  your  video  display. 

data  Any  numeric  or  string  constant  or  variable. 

Enclose  string  constants  within  quotation 
marks.  All  data  items  must  be  separated  by  a 
semicolon  or  comma. 


Notes: 


If  you  specify  more  than  one  data  item  in  the  statement, 
separate  them  with  commas  or  semicolons. 

If  you  use  commas,  PRINT  automatically  advances  to  the 
next  tab  zone  before  printing  the  next  item.  In  BASIC09, 
tab  zones  are  16  characters  apart. 

If  you  use  semicolons  or  spaces  to  separate  data  items, 
BASIC09  prints  the  items  without  any  spaces  between 
them.  BASIC09  begins  the  next  print  item  immediately  fol- 
lowing the  end  of  the  last  print  item. 

If  you  end  a  print  item  without  any  trailing  punctuation, 
PRINT  begins  printing  at  the  beginning  of  the  next  line. 
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•  If  the  data  being  printed  is  longer  than  the  display  screen 
width,  PRINT  moves  to  the  next  line  and  continues  print- 
ing the  data. 

•  TAB  causes  BASIC09  to  begin  displaying  the  specified  data 
at  the  column  position  specified  by  TAB.  If  the  output  line 
is  already  past  the  specified  TAB  position,  PRINT  ignores 
TAB. 

•  You  can  concatenate  items  for  printing  using  the  plus  (  +  ) 
symbol,  for  example:  print  "hello  "*name$»"  " 
+  las  t  name$, 

•  PRINT  displays  REAL  numbers  with  nine  or  fewer  digits 
in  regular  format.  It  displays  REAL  numbers  with  more 
than  nine  digits  in  exponential  format.  For  example, 
1073741824  is  displayed  as  1  . 073741 82E+ 09. 

•  You  must  enclose  string  constants  within  quotation  marks. 
Examples: 

PRINT  A$ 

PRINT  "Menu  Items" 

PRINT  COUNT 

PRINT  VALUE,TEMP+(n/2.S),LaCATIDN$ 

PRINT  #PR  INTER—PATH,  "The  result  is  "-.NUMBER 

PRINT  #0UTPATH  FMT$ , COUNT .VALUE 

PRINT  "what  is"*NAME$*,"s  age?  "; 

PRINT   "INDEX:    " ; I ;TAB(25) ; "VALUE :       ";VALUE 
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Sample  Program: 

This  procedure  asks  you  to  type  a  word  or  phrase,  then  displays 
it  backwards  by  reading  each  character  from  end  to  beginning 
and  using  PRINT  to  display  it  on  the  screen, 

PROCEDURE  reverse 

GDIM  PHRASE,TITLE:STRING;  T, BEGIN : INTEGER 

DDIM  INSTRUCTIDNS:STRINGC43] 
GTITLE-"Word  Reversing  Program" 

3INSTRUCTI0NS""Type  a  word  or  phrase  you  want  to 
reverse:  " 
DPRINT  TITLE 

DPR  I  NT  " " 

DWHILE  PHRASEo""  DO 

DPRINT 

DPRINT  INSTRUCTIONS 

GINPUT  PHRASE 

OBEGIN-LEN(PHRflSE) 

DPRINT  "This  Is  how  your  phrase  looks  backwards:" 

DFOR  T-BEGIN  TO  1  STEP  -1 

DPRINT  MID$(PHRASE,T,1 >; 

DNEXT  T 

DPRINT 

DENDWHILE 

DEND 
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PRINT  USING    Displays  formatted  text 


Syntax:      PRINT  [#path]  USING  [format,]  data[;data...\ 


Function:  Prints  data  using  a  format  you  specify.  This  state- 
ment is  especially  useful  for  printing  report  headings, 
accounting  reports,  checks,  or  any  document  requiring  a  spe- 
cific format.  USING  is  actually  an  extension  of  the  PRINT 
statement;  therefore,  the  same  rules  that  apply  to  the  PRINT 
statement  also  apply  to  the  PRINT  USING  statement  (see 
PRINT). 

Parameters: 

path  The  number  corresponding  to  an  opened  device 

or  file.  If  you  do  not  specify  path,  the  default 
is  #1,  the  video  screen  (standard  output 
device).  To  print  to  another  device  or  file,  first 
OPEN  a  path  to  that  file  or  device  (see 
OPEN). 

format  An  expression  specifying  the  arrangement  of 

the  displayed  data. 

data  Any  numeric  or  string  constant  or  variable. 

Always  enclose  string  constants  within  quota- 
tion marks.  Each  data  item  must  be  separated 
by  semicolons  or  commas. 

Notes: 

Each  PRINT  USING  format  specifier  begins  with  a  single  identi- 
fier letter  that  specifies  the  type  of  format,  as  shown  in  the  fol- 
lowing table: 

B  Boolean  format 

E  exponential  format 

H  hexadecimal  format 

I  integer  format 

R  real  format 

S  string  format 
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Follow  the  identifier  letter  with  a  constant  number  that  specifies 
the  field  width.  This  number  indicates  the  exact  number  of  print 
columns  the  output  occupies.  It  must  allow  for  both  the  data  and 
any  overhead  characters,  such  as  sign  characters,  decimal  points, 
exponents,  and  so  on. 

Optionally,  you  can  add  a  justification  indicator  to  the  format 
expression.  The  indicators  are  <,  >,  and  A.  The  meaning  of  these 
indicators  varies,  depending  on  the  format  type  in  which  you  use 
them.  See  the  format  type  descriptions  for  specific  information. 

Note:  Do  not  use  any  spaces  within  format  expressions. 

The  following  are  the  format  type  descriptions: 

Real 

Use  this  format  for  real,  integer,  or  byte  type  numbers.  The  total 
field  width  specification  must  include  two  overhead  positions  for 
the  sign  and  decimal  point.  The  field  width  has  two  parts,  sepa- 
rated by  a  period.  The  first  part  specifies  the  integer  portion  of 
the  field.  The  second  part  specifies  how  many  fractional  digits  to 
display  to  the  right  of  the  decimal  point. 

If  a  number  has  more  significant  digits  than  the  field  allows, 
BASIC09  uses  the  undisplayed  digits  to  round  the  number 
within  the  correct  field  width. 

The  justification  modes  are: 

<       Left  justify  with  leading  sign  and  trailing  spaees.  This  is 
the  default  if  you  omit  a  justification  indicator. 

>       Right  justify  with  leading  spaces  and  sign. 

"       Right  justify  with  leading  spaces  and  trailing  sign 
(financial  format). 

Some  examples  and  their  results  are: 

PRINT   USING   "R8.2<", 5678. 123 
PRINT   USING   "R8.2>",S678.123 
PRINT   USING   "R8.2>,,,12.3 
PRINT   USING   "R8.2>",-555.9 
PRINT    USING   "R1B.2*M, -6722. 4599 


5678, 

,12 

5678. 

,12 

12, 

,30 

-555. 

,90 

6722.46 
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Exponential 

Use  this  format  to  display  real,  integer,  or  byte  values  in  the  sci- 
entific notation  format — using  a  mantissa  and  decimal  exponent. 
The  field  has  two  parts:  the  first  part  must  allow  for  six  overhead 
positions  for  the  mantissa  sign,  decimal  point,  and  exponent 
characters. 

The  justification  modes  are: 

<  Left  justify  with  leading  sign  and  trailing  spaces.  This  is 
the  default  if  you  omit  a  justification  indicator. 

>  Right  justify  with  leading  spaces  and  sign. 

Some  examples  and  their  results  are: 

PRINT   USING   "E1 2.3" ,1234.587  1.23SE+03 

PRINT   USING   ,,E13.6>",-.  001234      -1  .234000E-03 
PRINT   USING   "El 8. S>" ,123456789  1.234575*08 

Integer 

Use  this  format  to  display  integer,  byte,  or  real  type  numbers  in 
an  integer  or  byte  format.  The  field  width  must  allow  for  one 
position  of  overhead  for  the  sign. 

The  justification  modes  are: 

<  Left  justify  with  leading  sign  and  trailing  spaces.  This  is 
the  default  if  you  omit  a  justification  indicator. 

>  Right  justify  with  leading  spaces  and  sign. 
A       Right  justify  with  leading  sign  and  zeroes. 

Some  examples  and  their  results  are: 

PRINT  USING  "I4<",10     10 
PRINT  USING  "I4<",10      1 0 
PRINT  USING  "I4"M,-10   -010 

Hexadecimal 

Use  this  format  to  display  any  data  type  in  hexadecimal  nota- 
tion. The  field  width  specification  determines  the  number  of 
hexadecimal  characters  BASICQ9  displays.  If  the  data  to  display 
is  string  type,  this  function  displays  the  ASCII  value  of  each 
character  in  hexadecimal. 
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The  justification  modes  are: 

<       Left  justify  with  trailing  spaces.  This  is  the  default  if 
you  omit  a  justification  indicator. 

>       Right  justify  with  leading  spaces. 

*       Center  digits. 

The  number  of  bytes  of  memory  used  to  represent  data  varies 
according  to  data  type.  The  following  chart  suggests  field  widths 
for  specific  data  types: 


Type 


Memory 
Bytes 


Field  Width 
To  Specify 


Boolean  and  Byte 

Integer 

Real 

String 


1 

2 
5 

1  per 
character 


2 

4 
10 

2  times  the  string 
length 


Some  examples  and  their  results  are: 

PRINT   USING   "H4",100  0064 

PRINT   USING   ,,H4",-1  FFFF 

PRINT   USING   "HS-'V'ABC"      414243 

String 

Use  this  format  to  display  string  data  of  any  length.  The  field 
width  specifies  the  total  field  size.  If  the  string  to  display  is 
shorter  than  the  field  size,  PRINT  USING  pads  it  with  spaces 
according  to  the  justification  mode.  If  the  string  to  display  is 
longer  than  the  specified  field  width,  PRINT  USING  truncates 
the  right  portion  of  the  string. 

The  justification  modes  are: 

<       Left  justify  with  trailing  spaces.  This  is  the  default  if 

you  omit  a  justification  indicator. 

>       Right  justify  with  leading  spaces. 
"       Center  characters. 
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Some  examples  and  their  results  are: 

PRINT   USING   "S9<", "HELLO"         HELLO 
PRINT   USING   "S9>'\ "HELLO"  HELLO 

PRINT   USING   "S9*", "HELLO"  HELLO 

Boolean 

Use  this  format  to  display  Boolean  expression  results.  BASIC09 
converts  the  result  of  the  expression  to  the  strings  "True"  or 
'Talse."  The  format  and  results  are  identical  to  STRING  formats. 
The  justification  modes  are: 

<       Left  justify  with  trailing  spaces.  This  is  the  default  if 
you  omit  a  justification  indicator. 

>       Right  justify  with  leading  spaces. 

*       Center  characters. 

If  A  =  5  and  B  =  6,  some  examples  and  their  results  are: 

PRINT   USING   "B9<",A<B        True 
PRINT   USING   "B9>,,,fi>B  False 

PRINT   USING   "B9"",A«B  False 

Control  Specifiers 

You  can  also  use  control  specifiers  within  PRINT  USING  for- 
mats. The  three  specifiers  are: 

Tn  Tab.  n  specifies  a  tab  column  at  which  to  display 

the  next  data. 

Xn  Spaces,  n  specifies  a  number  of  spaces  to  insert. 

'text*         Constant  string,  text  is  a  string  that  is  constant  to 
the  format. 

An  example  and  its  result  is: 

PRINT   USING   "'Address', X1 ,H4,X4, 'Data', XI  ,H2", 

1000,100 

Address    03E8  Data    64 
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Repeat 

Tfou  can  repeat  identical  sequences  of  specifications  using  paren- 
theses within  a  format  specification.  Enclose  the  group  of  speci- 
fications you  wish  to  repeat,  preceded  by  a  repetition  count,  such 
as: 

,,2CX2,^10.5>,,  in  place  of  "X2,Ri  0.5,X2,R1  b.S" 

"2<I2,2<X1 ,S4>>" in  place  of "12, X1 ,S4,X1 ,S4 , I2,X1  , 
S4.X1 ,S4" 

Sample  Program: 

This  program  looks  at  memory  locations  32000  to  32010  and  dis- 
plays their  contents  in  decimal,  hexadecimal,  and  binary.  PRINT 
USING  formats  the  display  in  columns. 

PROCEDURE  memlook 

DDIM  NUMBER, T, MEM, VALUE: INTEGER 

DDIM  X.NUM: INTEGER;  CHARACTER ,BI : STRING 

GPRINT  "DAddr.DDec.DHex.CBirirnLTLXIASCI  I" 

HFOR  2=32088  TO  3201 0 

2BI 

DNUMBER-PEEKCZ) 

31 F    NUMBER>0  THEN 

DGOSUB  100 

DENDIF 

GIF  PEEKCZX32  THEN 

.GCHARACTER-M" 

GELSE 

aCHARACTER=CHR*<PEEK(Z>> 

HENDIF 

GIF    PEEKCZ)>0    THEN 

DPRINT    USING   "I6<,T7,I4<,X2,H4<,X1 ,S8< , X2 ,S1 ",Z, 

PEEK(Z>,PEEKCZ) ,BI .CHARACTER 

HEL5E    PRINT   USING   "I6< ,T7, I4< , X2,H4< ,X1 ,S8> ,X2, 

S1,,,Z,B,B,,,BBB0,,,H    " 

jENDIF 

:next  z 

ZEND 
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1 0  0QNUM-LDG1 0( NUMBER)/. 3 

DNUM-2ANUM 

DREPEAT 

DX=NUMBER/NUM 

DIF    X>0   THEN   Bi-BI+"1" 

DNUMBER-MOD< NUMBER, NUM) 

DELSE  BI«BI+"0" 

DENDIF 

DNUM=NUM/2 

DUNTIL  NUM<«1 

DIF  NUMBER>0  THEN 

DBI -BI +"1 " 

DELSE   BI-BI+"0" 

DENDIF 

DRETURN 

DEND 
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-PU  1     Writes  to  a  direct  access  file 


Syntax:      PUT  #path,data 

Function:  Writes  a  fixed-size  binary  data  record  to  a  file  or 
device.  Use  PUT  to  store  data  in  random  access  files. 

Although  you  usually  use  PUT  with  files,  you  can  also  use  it 
to  send  data  to  a  device. 

For  information  about  storing  data  in  random  access  files,  see 
Chapter  8,  "Disk  Files".  Also,  see  GET,  SEEK,  and  SIZE. 

Parameters: 

poth  A  variable  name  you  chose  to  use  in  an  OPEN 

or  CREATE  statement  that  stores  the  number 
of  the  path  to  the  file  or  device  to  which  you 
are  directing  data. 

data  Either  a  variable  containing  the  data  you 

want  to  send  or  a  string  of  data. 

Examples: 

PUT  #PATH,DATA$ 

PUT  INPUT, ARRAY* 

Sample  Program: 

This  procedure  is  a  simple  inventory  data  base.  You  type  in  the 
information  for  an  item  name,  list  cost,  actual  cost,  and  quan- 
tity. Using  PUT,  the  procedure  stores  data  in  a  file  named 
Inventory. 

PROCEDURE  inventory 

DTYPE  INV_ITEM-NAME:STR1NGC25];  LIST, COST: REAL; 

QTY: INTEGER 

IDIM  INV_ARRAY(100):  INV__ITEM 

"DIM  WDRK_REC:INv_ITEM 

IDIM   PATH: BYTE 

jON    ERROR    GOTO    10 
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DDELETE    "inventory" 

10DDN    ERROR 

□CREATE  #PATH, "inventory" 

DWORK_REC.NAME 

□WORK_REC.LIST=0 

DWDRK_REC.COST-0 

□WORK_REC.QTY-0 

□FOR  N-1  TO  100 

DPUT  #PATH,WQRK_REC 

□NEXT  N 

CLOOP 

DINPUT  "Record  number?  ".recnum 

□IF  recnum<1  OR  recnum>1 00  THEN 

□PRINT 

DPR1NT  "End  of  Session" 

GPRINT 

□CLOSE  #PATH 

□ENB 

□END  IF 

□INPUT  "Item  name?  " ,WORK_REC .NAME 

□  INPUT  "List  price?  " ,WORK_REC . L I  ST 

DINPUT  "Cost  price?  " ,WORK_REC . COST 

JINPUT  "Quantity?  "  ,W0RK_REC  .  Q.TY 

L"SEEK  *PATH,<recnum-1  >»SIZE(WORK_REC> 

□PUT  #PATH,UORK_REC 

□ENDLODP 

□END 
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Xv AAj    Returns  trigonometric  calculations  in 
radians 


Syntax:      RAD 


Function:  Set  a  procedure's  state  flag  so  that  a  procedure  uses 
radians  in  SIN,  COS,  TAN,  ACS,  ASN,  and  ATN  functions. 
Because  this  is  the  BASIC09  default,  you  do  not  need  to  use 
the  RAD  statement  unless  you  previously  used  a  DEG  state- 
ment in  the  procedure. 

Parameters:  None 

Examples: 

RAD 

Sample  Program: 

This  program  calculates  sine,  cosine,  and  tangent  for  a  value  you 
supply.  It  calculates  one  set  of  results  in  degrees,  using  DEG, 
and  the  second  set  of  results  in  radians  using  RAD. 

PROCEDURE    trigcalc 

GDIM   ANGLE:REAL 

DDEG 

DINPUT   "Enter    the   angle    of    two    aides    of    a 

triangle. . .".ANGLE 

GPR1NT 

CPRINT   "[HIinHIAngle", "SINE"  ."COSINE", "TAN" 

CPRINT  "rmnrrm 


CPRINT  "Degrees  *  ";  ANGLE ,51 N< ANGLE) ,CDSC ANGLE)  , 

TAN(ANGLE) 

CRAD 

CPRINT  "Radians  =  ";  ANGLE, SIN(ANGLE) .COSCANGLE) , 

TANCANGLE) 
DPR  I  NT 
DEND 
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IX-Cj  AD    Reads  data  from  a  device  or  DATA 
statement 

Syntax:       READ  [#path,]  varname 


Function:  Reads  either  an  ASCII  record  from  a  sequential  file 
or  device,  or  an  item  from  a  DATA  statement. 

Parameters: 

path  A  variable  containing  the  path  number  of  the 

file  you  want  to  access.  You  can  also  specify 
one  of  the  standard  I/O  paths  (0,  1,  or  2). 

varname  The  variable  in  which  you  want  to  store  the 

data  read  from  a  file,  device,  or  DATA  line. 

Notes: 

The  following  information  deals  with  reading  sequential  disk 
files: 

•  To  read  file  records,  you  must  first  dimension  a  variable  to 
contain  the  path  number  of  the  file,  then  use  OPEN  or 
CREATE  to  open  a  file  in  the  READ  or  UPDATE  access 
mode.  The  command  begins  reading  records  at  the  first 
record  in  the  file.  After  it  reads  each  item,  it  updates  the 
pointer  to  the  next  item. 

•  Records  can  be  of  any  length  within  a  file.  Make  sure  the 
variable  you  use  to  store  the  records  is  dimensioned  large 
enough  to  store  each  item.  If  the  variable  storage  is  too 
small,  BASIC09  truncates  the  record  to  the  maximum  size 
for  which  you  dimensioned  the  variable.  If  you  do  not  indi- 
cate a  variable  size  with  the  DIM  statement,  the  default  is 
32  characters. 

•  BASIC09  separates  individual  data  items  in  the  input 
record  with  ASCII  null  characters.  You  can  also  separate 
numeric  items  with  comma  or  space  character  delimiters. 
Each  input  record  is  terminated  by  a  carriage  return 
character. 
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The  following  information  deals  with  reading  DATA  items: 

•  READ  accesses  DATA  line  items  sequentially.  Each  string 
type  item  in  a  DATA  line  must  be  surrounded  by  quotation 
marks.  Items  in  a  DATA  line  must  be  separated  with 
commas. 

•  Each  READ  command  copies  an  item  into  the  specified 
variable  storage  and  updates  the  data  pointer  to  the  next 
item,  if  any. 

•  You.  can  independently  move  the  pointer  to  a  selected  DATA 
statement.  To  do  this,  use  line  numbers  with  the  DATA 
lines  See  the  DATA  and  RESTORE  commands  for  more 
information  on  using  this  function  of  READ. 

Examples: 

READ   'PATH, DATA 

READ  #1  .RESPONSE! 

READ  'INPUT, INDEXCXJ 

FOR  T=1  TO  10 

READ  NAMEKT) 

NEXT  T 

DATA  " J IM" ," JOE" , "SUE" , "TI NA" , "WENDY" 

DATA  "SALL'VM  I  CK  IE",  "FRED",  "MARV"  ."WINNIE" 
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Sample  Program: 

This  procedure  puts  random  values  between  1  and  10  into  a  disk 
file,  then  READS  the  values  and  uses  asterisks  to  indicate  how 
many  times  RND  selected  each  value. 

PROCEDURE  randllst 

CDIM  SHOW,BUCKET:STRING 

CDIM  T,PATH,SELECT(10),R:INTEGER 

OBUCKET""**  ***#****#«»»•»«»**»»»»»" 

DFOR  T-1  TO  10 

DSELECT(T>=0 

DNEXT   T 

DON    ERROR    GOTO    10 

DSHELL   "DEL    RANDFILE" 

10DON    ERROR 

DCREATE   'PATH.'Vandf ile" :UPDATE 

DFDR    T-1    TO    100 

DR  =  RND«)  +  1 

DWRITE    #PATH,R 

DNEXT    T 

DPRINT  "Random  Distribution" 

DSEEK  *PATH,0 

DFOR  T-1  TO  100 

DREAD  *PATH,NUM 

DSELECTCNUM)-SELECT<NUM)+1 

DNEXT  T 

DFOR  T-1  TO  10 

DSHOW»RIGHT$CBUCKET,SELECTCT>) 

DPRINT  USING  "S6<,I3<,S2<,S20<","Number", 

T," j ".SHOW 

DNEXT  T 

DCLOSE    #PATH 

DEND 
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rvJiijyi    Inserts  remarks  in  a  procedure 


Syntax:      REM  [text] 
(*  ItexQl*)] 


Function:  Inserts  remarks  inside  a  procedure.  BASIC09 
ignores  these  remarks;  they  serve  only  to  document  a  proce- 
dure and  its  functions.  Use  remarks  to  title  a  procedure,  show 
its  creation  date,  show  the  name  of  the  programmer,  or  to 
explain  particular  features  and  operations  of  a  procedure. 

Parameters: 

text  Comments  you  want  to  include  within  a 

procedure 

Notes: 

•  "Vbu  can  insert  remarks  at  any  point  in  a  procedure. 

•  The  second  form  of  REM,  using  parentheses  and  asterisks, 
is  compatible  with  Pascal  programming  structure. 

•  When  editing  programs,  you  can  use  the  exclamation  char- 
acter "!"  in  place  of  the  keyword  REM. 

•  BASIC09's  initial  compilation  retains  remarks,  but  the 
PACK  compile  command  strips  them  from  procedures. 

Examples: 

REM  this  is  a  comment 

(*  Insert  text  between  parentheses  and 

asterisks*) 

C*  or  use  only  one  parenthesis  and  asterisk 


11-135 


BASIC09  Reference 


Sample  Program: 

This  procedure  uses  the  various  forms  of  REM  to  explain  its 
operations. 

PROCEDURE  copydir 

DREW  Use  this  program  with  the 

D(*  GET  sample  program  to  •) 

0('  create  a  file  of  directory*) 

QC»  filenames,  then  copy  the*) 

□{♦  files  to  another  directory*) 

DDIM  PATH, T.COUNT: INTEGER;  FILE,JOB,DIRNM:STRING 

DOPEN  'PATH, "dlrf He": READ  (*  open  the  file 

DINPUT  "Name  of  new  directory.. .".DIRNAME  (♦  jet  the  directory 

DSHELL  "MAKD1R  "*DIRNArtE  («  create  a  newdlrectory 

DSHELL  "LDAD  COPY" 

DWHIIE  N0T(£OF(#PATH))  DD 

DREAD  #PATH,FILE  (♦  get  a  filename 

DJOB'flLE*"  "+DIRNAME*"/"*FILE  (*  create  the  COPY  syntax 

DON  ERROR  GOTO  18 

QPRINT  "COPY  ";  JOB  {«  display  the  operation 

DSHELL  "COPY  "+JDB  (»  copy  the  file 

ION  ERROR 

DENDWHRE 

DOLOSE  #PATH 

GEND 
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REPEAT/UNTIL 

Establishes  a  loop/Terminates  on  specified  condition 


Syntax:      REPEAT 

procedure  lines 
UNTIL  expression 


Function:  Establishes  a  loop  that  executes  the  encompassed 
procedure  lines  until  the  result  of  the  expression  following 
UNTIL  is  true,  Because  the  bop  is  tested  at  the  bottom,  the 
lines  within  the  loop  are  executed  at  least  once, 

Parameters: 

expression  A  Boolean  expression  (returns  either  True  or 

False). 

procedure  Statements  you  want  to  repeat  until  expression 

lines  returns  False. 


Examples: 


REPEAT 

COUNT  '    COUNT+1 

UNTIL  COUNT  >  100 

INPUT  X,Y 

REPEAT 

X  -  X-1 

Y  -  Y-1 

UNTIL  X<1  OR  Y<8 
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Sample  Program: 

The  procedure  sorts  a  disk  file.  In  this  case,  it  is  written  to  sort 
the  diskfile  created  by  the  GET  sample  program — a  directory 
listing.  It  uses  a  REPEAT/UNTIL  loop  to  compare  a  string  in 
the  file  with  the  first  string  in  the  file.  If  the  first  string  is 
greater  than  the  comparison  string,  the  procedure  swaps  them. 

PROCEDURE  dlrsort 

CDIM  BTEMP:B001EAN;  TEMP ,FILES( 1 25) : STRI NG ;  TOP, 

BOTTOM, M.N: INTEGER 

DDIM  T.X.PATH: INTEGER 

CFQR  T-1  TO  125 

CFILESm-"" 

GNEXT  T 

EIT-0 

DOPEN  #PATH,"dirf ile":READ 

DPRINT  "LOADING:" 

HWHILE    N0T<EOF<*PATH>)   DO 

GT-T+1 

OREAD   *PATH,FILESCT) 

DENDWHILE 

DTDP-T 

DB0TT0M-1 

DPR  I  NT   "SORTING;    " j 

10GN-BOTTOM 

L"M*TOP 

CPRINT   'V  ; 

CLOOP 

CREPEAT 

CBTEMP-FILES(NXFILES<TOP) 

CN'N+1 

DUNTIL    NOTCBTEMP) 

GN»N-1 

GEXITIF    N=M   THEN 

CENDEXIT 

DTEMP=FILEStM) 

DFILES(M>*FILES<N) 

ZIFILESCN)«TEMP 

QN=N+1 

DEXITIF  N»M  THEN 

DENDEXIT 
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GENDLODP 

GIF   NOTDP    THEN 

GIF   FILES(NX>FILES<TOP>    THEN 

CTEMP=FILES(N) 

CFILESCN)=FILES<TOP> 

CFILES<TDPJ-TEMP 

DENDIF 

DENDIF 

DIF  B0TT0M<N-1  THEN 

GTOP-N-1 

CGDTD  10 

DENDIF 

DIF  N  +  KTDP  THEN 

DBOTTDM-N+1 

DGOTO  1 0 

DENDIF 

GCLOSE  *PATH 

GDELETE  "dirfile" 

GCREATE  #PATH,"dirfile":WRITE 

DPR  I  NT 

GFOR  Z=1  TO  T 

GWRITE  #PATH,FILES(Z) 

GPRINT  FILESCZ), 

GNEXT  Z 

GCLOSE  #PATH 

GEND 
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RESTORE    Resets  READ  pointer 


Syntax:      RESTORE  linenumber 

Function:  Sets  the  pointer  for  the  READ  command  to  the 
specified  line  number.  RESTORE  without  a  line  number  sets 
the  data  pointer  to  the  first  data  statement  in  the  procedure. 

READ  assigns  the  items  in  a  DATA  statement  to  variable 
storage.  When  you  read  an  item,  the  pointer  automatically 
advances  to  the  next  item.  Using  RESTORE  you  can  skip 
backward  or  forward  to  data  items  at  a  specific  line  number. 

Parameters: 

linenumber       The  line  number  of  the  DATA  items  you  want 
READ  to  access  next. 

Examples: 

RESTORE    1 00 

Sample  Program: 

This  procedure  draws  a  box  on  the  screen.  It  uses  RESTORE  to 
repeat  the  data  in  line  20  to  create  the  sides  of  the  box. 

PROCEDURE  box 

DDIM  LINE:STRING 

DREAD  LINE 

DPR  I  NT  LINE 

DFOR  T-1  TO  1 0 

DRESTORE  20 

3READ  LINE 

GPRINT  LINE 

DNEXT  T 

DRESTORE  10 

DREAD  LINE 

DPRINT  LINE 

1 0DDATA  " " 


2  0gd  a  t  a  "cninmjiHnnnnn] 
:end 
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Ixfci  1  U  xCJN     Returns  from  subroutine 


Syntax:       RETURN 


Function:  Returns  procedure  execution  to  the  line  immedi- 
ately following  the  last  GOSUB  statement. 

Every  subroutine  you  access  with  GOSUB  must  contain  a 
RETURN  statement.  "You  can  call  a  subroutine  in  this  man- 
ner as  many  times  as  you  want. 

Parameters:  None 


Sample  Program: 

This  procedure  draws  a  design  of  asterisks  down  the  display 
screen.  It  uses  MOD  to  send  execution  to  a  series  of  PRINT 
USING  routines  over  and  over.  Each  PRINT  USING  routine 
sends  execution  back  to  the  main  routine  with  a  RETURN 
statement. 


PROCEDURE  stars 

IDIM  T: INTEGER 

3SHELL  "TMDDE  -PAUSE 

ZIFOR  T-1  TO  100 

DON  M0D(T,8J*1  GOSUB 

DNEXT  T 

DSHELL  "TMDDE  PAUSE" 

DEND 

10DPRINT  USING  "S10* 

20CPRINT  USING  "S10" 

30CPRINT  USING  "51  0" 

40IPRINT  USING  "S1 0" 

S0ZPRINT  USING  "S1 0* 

60DPRINT  USING  "S1  0* 

70HPRINT  USING  "S10* 

80JPRINT  USING  "S10" 

JEND 


1 0,20,30,40,50,60,70,80 


»"  \  RETURN 
»»"  \  RETURN 
»•»"  \  RETURN 
»••••>  \  RETURN 

\  RETURN 

»««*"    \    RETURN 
»»*"    \    RETURN 
•*"    \    RETURN 
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xvllxri  1  tp    Returns  specified  rightmost  portion 
of  a  string 


Syntax:      RlGHT$(string,leDgtti) 

Function:  Returns  the  specified  number  of  characters  from  the 
right  portion  of  the  specified  string.  If  length  is  the  same  as  or 
greater  than  the  number  of  characters  in  string,  then  RIGHTS 

returns  all  of  the  characters  in  the  string. 

Parameters: 

string  A  sequence  of  string  type  characters  or  a  vari- 

able containing  a  sequence  of  string  type 
characters. 

length  The  number  of  characters  you  want  to  access. 

Examples: 

PRINT   RIGHTSCHOTDOG"^) 
PRINT   RIGHT$<A$,6> 

Sample  Program: 

PROCEBURE    lastname 

DDIM   NAMES:STRING;    LASTNAME :STRI NGC1  0] 

DPRINT   "Here   are    the    last    names:" 

OFQR   T-1    TD    1 0 

DREAD    NAMES 

OPOINTER-SUBSTRC"   •' , NAMES) 

CPQ I NTER-LEN( NAMES) -POINTER 

DLASTNAME-R I GHT$( NAMES, POINTER) 

DPRINT   LASTNAME 

GNEXT   T 

DDATA  "Joe  Blonak i" ,"Mi ke  Marvel" ,"Hal  Skeemish", 

"Fred  Langly" 

DDATA    "Jane   Misty" , "Wendy   Paston" , "Martha 

Upahong","Jacqual ine    Rivers" 

DDATA    "Susy   Reetmore" ,"Wi lson    Creding" 

DEND 
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£v  r\  JJ    Returns  a  random  value 


Syntax:      RND(fliunber) 

Function:  Returns  a  random  real  value  in  the  following 
ranges: 

If  number  =  0  then  range  =  0  to  1 

If  number  >  0  then  range  =  0  to  number 

The  values  produced  by  END  are  not  truly  random  numbers, 
but  occur  in  a  predictable  sequence.  Specifying  a  number  less 
than  0  begins  the  sequence  over. 

Parameters: 

number  A  numeric  constant,  variable,  or  expression. 

Examples: 

PRINT  RND(S) 
PRINT  RNDCA) 
PRINT  RND<A»5) 

Sample  Program: 

This  procedure  presents  addition   problems  for  you  to  solve. 
It  uses   RND   to   select  two  numbers  between   0    and   20. 
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PROCEDURE  addition 

DDIM  A, B, ANSWER, C: INTEGER 

DFOR   T-1    TD    5 

3A-RNDC20) 

CB-RND<20) 

GC=A+B 

DPRINT   USING   "'What    is O' , I3>", A 

dpr i nt  using  "'rnnri>D',i3>",B 
dprint  "nnnmnm ■■ 

DINPUT  "mCHDnDI]",  ANSWER 

DIF  ANSWER=C  THEN 

DPRINT   "CORRECT" 

DELSE 

DPRINT    "WRONG" 

OENDIF 

DPRINT 

DNEXT   T 

DEND 
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riU.N     Executes  another  procedure 


Syntax:       RUN  procname  i(param[,param,...])] 


Function:  Calls  a  procedure  for  execution,  passing  the  speci- 
fied parameters  to  the  called  procedure.  When  the  called  pro- 
cedure ends,  execution  returns  to  the  calling  procedure, 
beginning  at  the  statement  following  the  RUN  statement. 

RUN  can  call  a  procedure  existing  within  the  workspace,  a 
procedure  previously  compiled  by  the  PACK  command,  or  a 
machine  language  procedure  outside  the  workspace. 


Parameters: 

procname 


param 


The  name  of  the  procedure  to  execute.  The 
procname  can  be  the  literal  name  of  the  proce- 
dure to  execute,  or  it  can  be  a  variable  name 
containing  the  procedure  name. 

One  or  more  parameters  that  the  called  pro- 
gram needs  for  execution.  The  parameters  can 
be  variables  or  constants,  or  the  names  of 
entire  arrays  or  data  structures. 


Notes: 


Yiu  can  pass  all  types  of  data  to  a  called  program  except 
byte  type.  However,  you  can  pass  byte  arrays. 

If  a  parameter  is  a  constant  or  expression,  BASIC09  passes 
it  by  value.  That  is,  BASIC09  evaluates  the  constant  or 
expression  and  places  it  in  temporary  storage.  It  passes  the 
address  of  the  temporary  storage  location  to  the  called  pro- 
cedure. The  called  program  can  change  the  passed  values, 
but  the  changes  are  not  reflected  in  the  calling  procedure. 

If  a  parameter  is  the  name  of  a  variable,  array,  or  data 
structure,  BASIC09  passes  it  to  the  called  program  by  ref- 
erence. That  is,  it  passes  the  address  of  the  variable  storage 
to  the  called  procedure.  Thus,  the  value  can  be  changed  by 
the  receiving  procedure,  and  these  changes  are  reflected  in 
the  calling  procedure. 


11-145 


BASIC09  Reference 


•  If  the  procedure  named  by  RUN  is  not  in  the  workspace, 
BASIC09  looks  outside  the  workspace.  If  it  cannot  find  it 
there,  it  looks  in  the  current  execution  directory  for  a  disk 
file  with  the  proper  name.  If  the  file  is  on  disk,  BASIC09 
loads  and  executes  it,  regardless  of  whether  it  is  a  packed 
BASIC09  program  or  a  machine  language  program. 

If  the  program  is  a  machine  language  module,  BASIC09 
executes  a  JSR  (jump  to  subroutine)  instruction  to  its  entry 
point  and  executes  it  as  6809  native  code.  The  machine 
language  program  returns  to  the  original  calling  procedure 
by  executing  a  RTS  (return  from  subroutine)  instruction. 

•  After  you  call  an  external  procedure,  and  no  longer  need  it, 
use  KILL  to  remove  it  from  memory  to  free  space  for  other 
operations. 

•  Machine  language  modules  return  error  status  by  setting 
the  C  bit  of  the  MPU  condition  codes  register,  and  by  set- 
ting the  B  register  to  the  appropriate  error  code. 

Examples: 

RUN  CALCULATEC10,20,ADD> 
RUN  PRINTtTEXT$> 

Sample  Program: 

Makelist  creates  and  displays  a  list  of  fruit.  Next,  it  asks  you  to 
type  a  word  to  insert.  After  you  type  and  enter  a  new  word, 
Makelist  U9es  RUN  to  call  a  second  procedure  named  Insert  to 
look  through  the  list  and  insert  the  new  word  in  alphabetical 
order.  After  each  insertion,  the  procedure  asks  for  another  word. 
Press  only  [  enter  |  to  terminate  the  program. 

PROCEDURE  makelist 

DDIM  LISTC25>,NEWDRD,TEMPW0RD:STRING[15] 

DDIM  T, LAST: INTEGER 

OtAST=10 

DPRINT  "This  ia  your  list..." 

DFDR  T-1  TO  LAST 

DREAD  LISTCT) 

DPRINT  LISTCTJ, 

DNEXT   T 

DLODP 
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CPRINT 

DPRINT 

DINPUT  "Type  a  word  to  Insert ..." ,NEWORD 

DEXITIF  NEWORD THEN 

DPRINT 

QEND  "I've  ended  the  session  at  your  request 

DENDEXIT 

DRUN  InsertCLIST,NEWORD,LAST> 

DPRINT 

CPRINT  "This  is  your  new  list..." 

OFOR  T-1  TO  LAST 

DPRINT  LISTCT), 

DNEXT  T 

DPRINT 

DENDLDDP 

DDATA  "APPLES", "BANANAS", "CANTALOUPE" 

DDATA  "DATES", "GRAPES" ."LEMONS" 

DDATA  "MANGOS" , "PEACHES" , "PLUMS" 

DDATA  "PEARS" 

PROCEDURE  insert 

OP ARAM  LIST(2S),NEW0RD:STRING[1S1 

QPARAM  LAST: INTEGER 

DDIM  TEMPW0RD:STRING[15] 

DDIM  T,Xi INTEGER 

GT-1 

DWHILE  NEWORD>LISTtT)  DO 

DT=T+1 

GENDWHILE 

[]FOR  X-T  TO  LAST 

CTEMPWORD-LISTCX) 

DLIST<X)=NEWORD 

DNEW0RD=TEMPWORD 

DNEXT  X 

DLAST-LAST+1 

DLISTCLASTJ-NEWORD 

DEND 
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dUiCiiV    Resets  the  direct-access  file  pointer 


Syntax:       SEEK  #path,number 


Function:  Changes  the  file  pointer  address  in  a  disk  file.  The 
pointer  indicates  the  location'  in  a  file  for  the  next  READ  or 
WRITE  operation. 

You  usually  use  SEEK  with  random  access  files  to  move  the 
pointer  from  one  record  to  another,  in  any  order.  You  can  also 
use  SEEK  with  sequential  access  files  to  rewind  the  pointer 
to  the  beginning  of  the  file  (to  the  first  item  or  record). 

For  information  about  storing  data  in  random  access  files,  see 
Chapter  8,  "Disk  Files."  Also  see  PUT,  GET,  and  SIZE. 

Parameters: 

path  A  variable  name  you  choose  in  which  BASIC09 

stores  the  number  of  the  path  it  opens  to  the 
file  you  specify. 

number  The  item  or  record  number  you  want  to  access. 

If  you  are  rewinding  a  sequential  access  file, 
specify  a  number  of  0. 

Examples: 

SEEK    #PATH,0 

SEEK  #0UTF1LE,A 

SEEK  #INDEX,LOCATIDN*SIZECINVENTORY> 

Sample  Program: 

This  procedure  creates  a  file  named  Testl,  then  writes  10  lines 
of  data  into  it.  Next,  it  reads  the  lines  from  the  file  and  displays 
them.  It  uses  SEEK  to  both  store  and  extract  the  lines  in  blocks 
of  25  characters. 
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PROCEDURE  makelines 

cdim  length:byte 
cdim  line:stringc2s] 
cdim  pathibyte 

XENGTH-25 
DBASE    0 

DON    ERROR   GOTO    1 0 
DDELETE    "testl" 

1 0QON    ERROR 

DCREATE  #PATH,"test1"iWRITE 

DFOR  T=0  TO  9 

DREAD  LINE$ 

GSEEK  #PATH,LENGTH*T 

HPUT  #PATH, LINES 

CNEXT  T 

CCLDSE  #PATH 

COPEN  #PATH,"te5t1,,:READ 
DFOR  T-9  TO  0  STEP  -1 
DSEEK  #PATH,LENGTH*T 
ZIGET  *PATH,LINE 
GPRINT  LINE 
UNEXT  T 
JCLOSE  #PATH 
DEND 


DDATA 

"This 

is 

test 

line 

#1" 

DDATA 

"This 

is 

test 

line 

#2" 

CDATA 

"This 

is 

test 

line 

#3" 

CDATA 

"This 

is 

test 

line 

#4" 

CDATA 

"This 

is 

test 

line 

#S" 

CDATA 

"This 

i  s 

test 

line 

#6" 

CDATA 

"This 

i  s 

test 

line 

#7" 

CDATA 

"This 

i  s 

test 

line 

#8" 

CDATA 

"This 

i  s 

test 

line 

#9" 

CDATA 

"This 

i  s 

test 

line 

#1  0 
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feljrJN     Returns  a  value's  sign 


Syntax:      SGlSHmimber) 

Function:  Determines  whether  a  number's  sign  is  positive  or 
negative. 

If  number  is  less  than  0,  then  SGN  returns  -1.  If  number 
equals  0,  then  SGN  returns  0.  If  number  if  greater  than  0, 
then  SGN  returns  1. 

Parameters: 

number  The  value  for  which  you  want  to  determine  the 

sign. 

Examples: 

PRINT  SGN022) 
PRINT  SGN(A) 
PRINT  SGNC44-A) 

Sample  Program: 

This  procedure  uses  SGN  to  create  half  sine  waves  down  the 
screen.  SGN  tests  when  the  SIN  calculation  results  are  positive. 
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PROCEDURE  halfsine 

DDIM  FORMULA, CALCULATE.POSITI ON :REAL 

DSHELL  "DISPLAY  0C" 

CF0RMULA>(PI+2)/15 

CCALCULATE-FORMUIA 

DSHELL  "TMODE  -PAUSE" 

DFOR  T-0  TO  1 00 

CCALCULATE-CALCULATE+FORMUtA 

DPOSITION-INT<SIN(CALCULATEJ»10+16> 

DIF  SGN(SIN<CALCULATE>>>8  THEN 

DPR1NT  TAB<POS1TION>;  

CENDIF 

□NEXT  T 

QSHELL  "TMODE  PAUSE" 

GEND 
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SHELL 


Forks  another  shell 


Syntax:       SHELL  ["string"][  +  "atring"...][  +  variable] 
[  +  variable...] 


Function:  Executes  OS-9  commands  or  programs  from  within 
a  BASIC09  procedure.  Using  SHELL,  you  can  access  OS-9 
functions,  including  multiprogramming,  utilities,  commands, 
terminal  and  input/output  control,  and  so  on. 

When  you  use  the  SHELL  command,  OS-9  creates  a  new  pro- 
cess to  handle  the  commands  you  provide.  If  you  specify  an 
operation,  BASIC09  evaluates  the  expression  and  passes  it  to 
the  shell  for  execution.  If  you  do  not  specify  an  operation, 
BASIC09  temporarily  halts,  and  the  shell  process  displays 
prompts  and  accepts  commands  in  the  normal  manner.  In  this 
case,  press  I  ctrl  ||  break]  to  return  to  BASIC09. 

When  the  shell  process  terminates,  BASIC09  becomes  active 
and  resumes  execution  at  the  statement  following  the  SHELL 

statement. 

Parameters: 

string  Any  OS-9  command  or  function.  String  con- 

stants must  be  enclosed  in  quotation  marks. 
Concatenate  string  constants  and  string  vari- 
ables using  a  plus  symbol  (  +  ). 

variable  Any  string  variable  containing  an  OS-9  com- 

mand or  function. 


11-152 


BASIC09  Command  Reference  1 11 


Examples: 

SHELL  "COPY  FILE1  FILE2" 

SHELL  "COPY  FILE1  FILE24" 

SHELL  "COPY  "+FILE$+"  "+DIRNAME*"/"FILE$ 

SHELL  "LIST  DOCUMENT" 

SHELL  "KILL  "+STR$(N) 

Sample  Program: 

Yoxi  must  use  this  procedure  with  the  GET  sample  program. 

Using  the  two  programs  together  enables  you  to  copy  all  the  files 
from  one  directory  to  another  directory.  The  GET  sample  pro- 
gram reads  the  files  in  a  directory  and  stores  them  in  a  file 
named  Dirfile.  This  procedure  reads  the  filenames  from  Dirfile 
and  uses  SHELL  to  copy  them  to  the  directory  you  specify. 

PROCEDURE  copyutll 

DDIM  PATH.T, COUNT: INTEGER;  FILE, JDB.DIRNAME :STRIN6 

DQPEN  *PATH,"dirfile":READ 

DINPUT  "Name  of  new  directory .. .".DIRNAME 

DSHELL  "KAKDIR  "+DIRNAME 

DSHELL  "LOAD  COPY" 

DWKILE  N0T<E0F(#PATH))  DO 

DREAD  #PATH,FILE 

DJOB  =  FILE  +  "  "♦DIRNAME*"/,,  +  FI.LE 

DON  ERROR  GOTO  10 

DPR  I  NT  "COPY  ";  JOB 

DSHELL  "COPY  "  +  JOB 

10DON  ERROR 

DENDWHILE 

CCLQSE  'PATH 

GEND 
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OlJN     Returns  the  sine  of  a  number 


Syntax:      SIN(number) 


Function:  Calculates  the  trigonometric  sine  of  number.  You 
can  use  the  DEG  or  RAD  commands  to  cause  number  to  rep- 
resent a  value  in  either  degrees  or  radians.  Unless  you  specify 
DEG,  the  default  is  radians.  SIN  returns  a  real  number. 

Parameters: 

number  The  angle  of  two  sides  of  a  triangle  for  which 

you  want  to  find  the  ratio. 

Examples: 

PRINT  SINC4S) 

Sample  Program: 

This  procedure  calculates   sine,   cosine,   and   tangent    values 
for  a  number  you  type. 

PROCEDURE  rattocalc 

DDEG 

DDIM  ANGLE:REAL 

DINPUT  "Enter  the  angle  of  two  sides  of  a 

triangle. . .".ANGLE 

QPRINT 

DPR  I  NT  ,,Angle","SINE","CDSINE","TAN" 

DPR  INT" 


DPR  I  NT  ANGLE, S INC  ANGLE >,CQS< ANGLE ),TAN( ANGLE) 

DPR  I  NT 

DEND 
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SIZE    Returns  the  size  of  a  data  structure 


Syntax:      SIZE(  variable) 

Function:  Returns  the  size  in  bytes  of  a  variable,  array,  or 
data  structure.  SIZE  is  especially  useful  with  random  access 
files  to  determine  the  size  of  records  to  store  in  a  file.  %u  can 
also  use  SIZE  to  determine  the  size  of  variable  storage  for 
other  purposes. 

SIZE  returns  the  size  of  assigned  storage,  not  necessarily  the 
size  of  a  string.  For  example,  if  you  dimension  a  variable  for 
15  characters,  and  assign  a  10-character  string  to  it,  SIZE 
returns  15,  not  10.  SIZE  returns  the  total  size  of  arrays.  That 
is,  it  returns  the  number  of  elements  multiplied  by  the  size  of 
the  elements. 

Parameters: 

variable  The  variable,  array,  or  data  structure  for 

which  you  want  to  find  the  size. 

Examples: 

RECORDLENGTH  -  SIZECA*) 

PRINT  "YOUR  NAME  IS  STORED  IN  A  "j  S IZECNAME$> ; 
"  CHARACTER  STRING." 

Sample   Program: 

This  procedure  creates  a  simple  inventory,  stored  in  a 
file  named  Inventory.  It  uses  SIZE  to  calculate  the  size 
of  each  element  to  be  stored  in  the  file,  and  to  move 
the  pointer  to  the  beginning  of  each  record's  storage 
space. 
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PROCEDURE  inventory 

DTYPE  INV_ITEM=NAME:STRINGt25];  LIST , COST: REAL ; 

QTY: INTEGER 

CDIM  INV_ ARRAY(100):  INV_ITEM 

DDIM  WORK—REC:  I NV_ ITEM 

3DIM  PATHiBYTE 

DON  ERROR  GOTO  10 

DDELETE  "inventory" 

10DQN  ERROR 

DCREATE  *PATH, "inventory" 

OWORK— REC.NAME 

OWORK— REC.LIST-0 

QWORK— REC.COST-0 

GWORK— REC.GTY-0 

DFOR  N-1  TO  100 

DPUT  #PATH,WDRK_ REC 

DNEXT  N 

DLDOP 

DINPUT  "Record  number?  ",recnum 

DIF  recnum<1  OR  recnum>100  THEN 

DPRINT 

DPRINT  "End  of  Session" 

DPRINT 

CCLOSE  #PATH 

QEND 

HENDIF 

DINPUT   "Item   name?    ",WDRK_REC.NAME 

DINPUT   "List    price?    ", WORK—REC . L I  ST 

DINPUT   "Cost    price?    ",WORK_REC. COST 

DINPUT   "Quantity?    "  , WORK—REC . QTY 

DSEEK    #PATH,(recnum-1 >tSIZE(WORK— REC) 

CPUT   'PATH, WORK— REC 

L"ENDLODP 

GEND 
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Ok%    Returns  the  value  of  a  number  raised  to  the 
power  of  2 


Syntax:      SQinumber) 

Function:  Calculates  the  value  of  a  number  raised  to  the 
power  of  2, 

Parameters: 

number  The  number  you  want  raised  to  the  power  of  2. 

Examples: 

PRINT   SQ.C188) 
PRINT   PI»SQ<R) 

Sample  Program: 

This  procedure  uses  SQ  in  a  formula  that  positions  asterisks  on 
the  screen  in  a  sine  wave  pattern. 

PROCEDURE  sinedown 

DDIM  FORMULA, CALCULATE, POSITION: REAL 

DSHELL  "DISPLAY  0C" 

DF0RMULA-<PI+2)/1S 

DCALCULATE-FORMULA 

DSHELL  "TMODE  -PAUSE" 

LTDR  T=0  TO  200 

CCALCULATE=CALCULATE+SQ( FORMULA) 

CPOSITIDN-INT<SINCCALCULATE>*  12  +  18) 

CPRINT  TAB(POSITION);  "*'• 

CNEXT  T 

CSHELL  "TMODE  PAUSE" 

[END 
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DCqJ-K/oiqjxvl     Returns  the  square  root  of  a 

number 


Syntax:      SQR<numfcer) 
SQRT(number) 

Function:  Calculates  the  square  root  of  a  number.  SQR  and 
SQRT  serve  the  same  function. 

Parameters: 

number  The  number  for  which  you  want  the  square 

root. 

Examples: 

PRINT   SQRC188) 
PRINT   PI*SQRT(R) 

Sample  Program: 

This  procedure  uses  SQRT  in  a  formula  to  position  asterisks  on 
the  screen  in  a  sine  wave  pattern. 

PROCEDURE  sqrdown 

DDIM  FORMULA, CALCULATE, POSIT  I  ON: REAL 

QSHELL  "DISPLAY  AC" 

QFORMULA-PI/15 

DCALCULATE-FDRMULA 

DSHELL  "TMODE  -PAUSE" 

DFOR  T«0  TO  200 

QCALCULATE-CALCULATE+SQRTC FORMULA) 

0POSITIQN-INT<SIN<CALCULATE>»12*16> 

QPRINT  TABCPOSITIDN);  "♦" 

DNEXT  T 

DSHELL    "TMODE    PAUSE" 

QEND 
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0 1  Ji/"    Establishes  the  size  of  increments 
FOR  loop 


in  a 


Syntax: 

FOR  variable  ■  bait  val  TO  end  val  [STEP  value] 

[procedure  statements] 

NEXT  variable 


Function:  STEP  provides  an  increment  value  in  a  FOR/NEXT 
loop.  If  you  do  not  specify  a  STEP  value,  the  bop  steps  in 
increments  of  1. 

BASIC09  executes  the  lines  following  the  FOR  statement  until 
it  encounters  a  NEXT  statement.  Then  it  either  increases  or 
decreases  the  initial  value  by  1  (the  default)  or  by  the  value 
given  by  STEP.  If  you  give  the  loop  an  initial  value  that  is 
greater  than  the  final  value,  and  specify  a  negative  value  for 
STEP,  the  loop  decreases  from  the  initial  value  to  the  end 
value. 


Parameters: 

variable 
init  val 
end  val 
value 

procedure 

statements 


Any  legal  numeric  variable  name. 

Any  numeric  constant  or  variable. 

Any  numeric  constant  or  variable. 

Any  numeric  constant  or  variable. 

Procedure  lines  you  want  to  be  executed 
within  the  loop. 
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Examples: 


FDR  COUNTER  -1  to  1 00  STEP  .5 
PRINT  CDUNTER 
NEXT  COUNTER 

FOR  X  ■  18  TO  1  STEP  -1 
PRINT  X 
NEXT  X 

FDR  TEST  =  A  TO  B  STEP  RATE 
PRINT  TEST 
NEXT  TEST 

Sample  Program: 

This  procedure  reverses  the  order  of  characters  in  a  word  or 
phrase  you  type.  It  uses  STEP  to  decrement  a  counter  that 
points  to  each  character  in  the  string  in  reverse  order. 

PROCEDURE  reverse 

DDIM  PHRASE:STRING;  T ,BEGI N : I NTEOER 

DPRINT  "Type  a  word  or  phrase  you  want  to 

reverse : " ; 

DPRINT 

DINPUT  PHRASE 

DBEGIN*LEN(PHRASE> 

DPRI NT ■ "Thi 5  is  how  your  phrase  looks  backwards:" 

DFOR  T-BEGIN  TO  1  STEP  -1 

DPRINT  MID$(PHRASE,T,1 ); 

DNEXT  T 

DPRINT 

DEND 
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O I  \J  if    Terminates  a  procedure 


Syntax:      STOP  ["string"] 

Function:  Causes  a  procedure  to  cease  execution,  print  the 
message  "STOP  Encountered",  and  return  control  to 
BASICWs  command  mode.  "Vbu  can  also  specify  additional 
text  to  display  when  BASIC09  encounters  STOP. 

Use  stop  when  you  want  a  procedure  to  terminate  without 
entering  the  DEBUG  mode. 

Parameters: 

string  Text  to  display  when  STOP  executes. 

Examples: 

STOP  "Program  terminated  before  completion." 

IF  RESPONSE  =  "Y"  THEN  STDP  "Program  terminated 
at  your  request." 

ENDIF 
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feXxvtj)    Converts  numeric  data  to  string  data 


Syntax:      STR${iiumber) 

Function:  Converts  a  numeric  type  to  a  string  type.  This  lets 
you  display  the  number  as  a  string  or  use  string  operators  on 
a  number.  The  conversion  replaces  the  numeric  values  with 
the  ASCII  characters  of  the  number.  STR$  is  the  inverse  of 
the  VhL  function. 

Parameters: 

number  Any  numeric-type  data. 

Examples: 

PRINT  STR$(1010) 

DIM  I: INTEGER 

1=44 

PRINT  STR$(I> 

DIM  B:BYTE 

B=001 

PRINT  STR$CB> 

DIM  R:REAL 
R*1234.56 

PRINT  STRSCR) 

Sample  Program: 

This  procedure  calculates  an  exponential  value,  then  adds  the 
necessary  number  of  zeroes  to  convert  it  to  standard  notation,  It 
uses  STR$  to  convert  the  number  you  type  to  a  string  type  value 
so  that  it  can  use  string  functions  to  add  the  zeroes. 
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PROCEDURE  bignum 

DDIM  C,  PLACES, B,SIGN:STRIN6;  EX , COUNT ,NEWCDUNT , 

DECIMAL: INTEGER 

DDIM  NEU,ZERQ,NEWEST:STRINGt100) 

DC0UNT--1 

Q2ERO-"000000000000000000000000000000000000" 

□MEW-""  \NEWEST-"" 

QINPUT  "What  number  do  you  want  to  raise  to  the 

power  of  14?...",  NUM 

DA-NUfP14 

GB=STR$CA) 

GEX=SUBSTR("E",B> 

QSI0N=MID$(B,EX+1 ,1 ) 

GPLACES-RIGHT$<B,LENCB)-EX-1 ) 

GFOR  T-1  TO  LEN<B) 

GC=MID$CB,T,1  > 

GIF  C="."  THEN 

GDECIMAL-0 

GGOTO  10 

GENDIF 

QDECIMAL-DECIMAL+1 

OIF  C»"E"  THEN  100 

GNEW-NEW+C 

10DNEXT  T 

1 0  0DNEWCOUNT-VALC PL ACES) -DECIMAL 

GNEW-NEW*LEFT$(ZER0,NEWCOUNT+1> 

GFOR  T-LENCNEW)  TO  1  STEP  -1 

DCOUNT-COUNT+1 

GNEWEST*MID$CNEW,T,1 >+NEWEST 

GIF  M0D<C0UNT,3>-2  AND  T>1  THEN 

[]NEWEST-","  +  NEWEST 

DENDIF 

GNEXT  T 

GPRINT  NUM;  "  to  the  power  of  14  »  ";  a 

GPRINT  "-  ";  NEWEST 

GEND 
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O  U  JjO  1  It    Searches  for  specified  characters  in 
a  string 

Syntax:      SUBSTR(targetstring,searchstrwg) 

Function:  Searches  for  the  first  occurrence  of  targetstring 
within  search-string  and  returns  the  numeric  value  of  its  loca- 
tion, SUBSTR  counts  the  first  character  in  searchstring  as 
character  Number  1.  Therefore,  if  you  searched  for  the  string 
"worth"  in  the  string  "Jbrtworth",  SUBSTR  returns  a  value  of 
5. 

If  SUBSTR  cannot  find  targetstring,  it  returns  a  value  of  0, 

Parameters: 

targetstring       The  group  of  characters  you  want  to  locate. 

searchstring      The   string   in   which   you   want  to   find 

targetstring. 

Examples: 

PRINT    SUBSTR C "THREE", "ONETWOTHREEFDURF IVES  IX") 
X=SUBSTR<"    ",FULLNAME$> 

Sample   Program: 

This  procedure  selects  the  last  name  from  a  string  con- 
taining both  a  first  name  and  a  last  name.  It  uses 
SUBSTR  to  find  the  space  between  the  two  names  in 
order  to  determine  where  the  last  name  begins. 
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PROCEDURE  laatname 

DDIM  NAMES:STRING;  LASTNAME:STRINGM  0  ] 

DPRINT  "Here  are  the  laat  names:" 

GFDR  T=1  TO  10 

DREAD  NAMES 

DPDINTER-SUBSTRC"  ",NAMES> 

DP0INTER-LEN<NAMES)-POINTER 

DLASTNAME-RIGHTSCNAMES, POINTER) 

CPRINT  LASTNAME 

DNEXT  T 

DDATA    "Joe   Blonski","Mike   Marvel" , "Hal 

Skeemlah" ,"Fred    Laungly" 

DDATA    "Jane   Ml  sty" , "Wendy   Paston" , "Mar tha 

Upshong","Jecquel ine    Rivera" 

DDATA    "Susy   Reetmore" , "Wi 1  son    Creding" 

DEND 


11-165 


BASIC09  Reference 


SYSCALL    Executes  an  OS-9  System  Call 


Syntax:      SYSCALL  callcode  registers 

Function:  Lets  you  execute  any  OS-9  system  call  from 
BASIC09.  Use  this  command  to  directly  manipulate  your  sys- 
tem or  data  or  to  directly  access  devices. 

Be  careful!  Used  improperly,  SYSCALL  can  cause  undesira- 
ble results — you  might  unintentionally  format  a  disk  or 
destroy  disk  or  memory  data.  Before  using  SYSCALL,  you 
should  be  familiar  with  assembly  language  programming  and 
should  understand  the  system  call  information  in  the  OS-9 
Technical  Reference  manual.  The  OS-9  Technical  Reference 
manual  provides  information  about  all  OS-9  system  calls. 

To  pass  required  register  values  to  the  SYSCALL  command, 
create  a  complex  data  structure  that  contains  values  for  all 
registers.  For  example: 

TYPE    REGISTERS=CC,A,a,DP:BYTE;    X , Y , U : I NTEGER 
DIM   REGS:REGISTERS 
DIM   CALLCODE :BYTE 

The  complex  data  type  REGISTERS  contains  values  for  all 
registers.  Unless  you  specifically  assign  values  to  variables 
(for  instance,  REGS.CC,  REGS.A,  and  REGS.B  in  the  pre- 
vious example),  they  contain  random  values.  See  the  TYPE 
command  for  further  information. 

Parameters: 

callcode  is  the  request  code  of  the  system  call  you  wish 

to  use.  All  system  call  codes  are  referenced  in 
the  OS-9  Technical  Reference  manual. 

registers  is  a  list  of  the  register  entry  values  required 

for  the  system  call  you  are  using. 

Examples:    see  "Sample  Programs." 
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Sample  Programs: 

The  following  programs  set  up  a  data  type  (REGISTERS)  for  the 
register  variables.  Before  executing  SYSCALL,  the  procedures 
store  the  required  register  entry  values  in  the  complex  data 
structure  REGS.  The  procedures  also  establish  CALLCODE  as  a 
variable  to  hold  the  request  code  of  the  system  call  you  want  to 
use. 

The  Writecall  procedure  uses  the  string  variable  TEST  to  store 
text  that  it  writes  to  the  screen  through  Path  0  (the  standard 
output  path)  using  System  Call  $8A,  I$Write.  Before  the  proce- 
dure calls  I$Write,  it  stores  the  appropriate  path  number  (0)  in 
Register  A.  The  ADDR  command  calculates  the  address  of  the 
variable  TEST,  and  the  LEN  command  determines  the  length  of 
the  variable.  The  procedure  stores  these  two  values  in  Registers 
X  and  Y. 

The  Readcall  uses  System  Call  $8B,  I$ReadLn  to  perform  a 

function  that  is  the  opposite  of  Writecall,  Readcall  establishes 
TEST  as  a  string  variable  into  which  it  writes  the  characters 
you  type.  Because  the  length  of  TEST  is  restricted  to  ten  charac- 
ters (DIM  TEST:STRiNGti03),  the  terminal  bell  sounds  if  you 
attempt  to  type  more  than  10  characters.  Pressing  [ENTER] 
terminates  the  call  and  the  procedure  prints  the  contents  of 
TEST — the  characters  you  typed. 


11-167 


BASIC09  Reference 


PROCEDURE  WriteCall 

DTYPE  REGISTERS=CC,A,B,DPiBYTE;  X ,Y ,Ui INTEGER 

DDIM  REGS: REGISTERS 

DDIM  PATH,CALLCODE:BYTE 

DDIM  TESTsSTRINGCSB] 

DTEST-"This  is  a  test  of  ISWrite,  System  call 

$8A. . . " 

DREGS. A-8 

DREGS.X*ADDR<TESTJ 

DREGS. Y=LEN<TEST) 

0CALLCODE-J8A 

DRUN  SYSCALL<CALLCODE,REGS> 

DPRINT 

DEND 

PROCEDURE  Readcall 

DTYPE  REGISTERS-CC,A,B,DP:BYTE;  X ,Y ,U : INTEGER 

DDIM  REGS  REGISTERS 

DDIM  PATH,CALLCODE:BYTE 
DDIM  TESTsSTRINGMfl] 

DREGS. A-0 

DREGS. X=ADDRCTESTJ 

DREGS. Y=10 

DCALLC0DE-$8B 

DRUN   SYSCALLCCALLCODE.REGS) 

DPRINT 

DPRINT    TEST 

GEND 
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X AiS    Causes  PRINT  to  jump  to  the  specified 
column 


Syntax:      TAB(numfcer) 


Function:  Causes  PRINT  to  display  the  next  PRINT  item  to 
display  in  the  column  specified  by  number.  If  the  cursor  is 
already  past  the  desired  tab  position,  BASIC09  ignores  TAB, 

Use  POS  to  determine  the  current  cursor  position  when  dis- 
playing characters  on  the  screen. 

Screen  display  columns  are  numbered  from  1,  the  leftmost  col- 
umn, to  a  maximum  of  255.  The  size  of  BASIC09  output 
buffer  varies  according  to  the  stack  size. 

You  can  also  use  TAB  with  PRINT  USING  statements. 

Parameters: 

number  The  column  at  which  you  want  PRINT  to 

begin. 

Examples: 

PRINT  TABC20>;TITLE$ 

PRINT  TABCX); ITEMNUMBER; ITEM* 

Sample  Program: 

This  procedure  uses  asterisks  to  simulate  a  sine  wave  on  the 
screen.  It  uses  TAB  to  position  each  asterisk  in  the  proper 

location. 
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PROCEDURE  ainewave 

DDIM  FORMULA, CALCULATE, POSITION: REAL 

DSHELL  "DISPLAY  0C" 

DF0RMULA=CPI+2)/1S 

DCALCULATE-FORMULA 

DSHELL  "TMDDE  -PAUSE" 

HFOR  T*0  TO  200 

DCALCULATE- CALCULATE +SQ< FORMULA} 

CPOSITION=INTCSINCCALCULATE)*12+16) 

DPR  I  NT  TABCPOSITION);  

DNEXT  T 

DSHELL    "TMDDE    PAUSE" 

DEND 
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J.  AJN     Returns  the  tangent  of  a  value 


Syntax:      TAN(number) 


Function:  Calculates  the  trigonometric  tangent  of  number. 
Using  DEG  or  RAD,  you  can  specify  the  measure  of  the  angle 
(number)  in  either  degrees  or  radians.  Radians  are  the  default 
units. 

Parameters: 

number  The  angle  for  which  you  want  to  find  the 

tangent. 

Examples: 

PRINT  TANC45) 

Sample  Program: 

This  procedure  calculates  sine,  cosine,  and  tangent  values  for  a 
number  you  type. 

PROCEDURE  ratiocalc 

ODEG 

DDIM  ANGLE:REAL 

QINPUT  "Enter  the  angle  of  two  sides  of  a 

triangle. . .".ANGLE 

jPRINT 

CPRINT  "Angle", "SINE", "COSINE", "TAN" 

CPRINT" 


GPRINT  ANGLE, S INC  ANGLE ),CQS< ANGLE ),TAN< ANGLE) 

DPR  I  NT 

DEND 
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1  .KliVltp    Removes  spaces  from  the  end  of  a  string 


Syntax:      TMM$(string) 

Function:  Removes  any  trailing  9paces  from  the  end  of  the 
specified  string.  This  function  is  particularly  useful  for  trim- 
ming records  you  recover  from  a  random  access  file. 

Parameters: 

string  The  string  or  string  variable  from  which  you 

wish  to  remove  trailing  spaces. 

Examples: 

PRINT  TRIMSCA$> 

SET  A$,B$,C$ 

PRINT  TRIM$CA$>,TRIM$(B$J,TRIM$(C«) 

Sample   Program: 

This  program  takes  names  you  type  and  puts  them  in  a 
random  access  disk  file.  Because  random  access  files  use 
the  same  amount  of  storage  for  each  item,  short  names 
are  padded  with  extra  spaces.  When  reading  the  names 
back  from  the  file,  the  procedure  uses  TRIM$  to  remove 
these  extra  spaces. 

PROCEDURE  namestor 

DDIM  NAMES.TEMP1  , NAME< 1 00) : STR I NGI26]  ;  FIRST, LAST: 

STRINGMS];  I N ITI AL :  STR  I NGE 1  ] 

CDIM  PATH, T: INTEGER 

CNAMES 

DON   ERROR   GOTO    10 

3DELETE    "nomelist" 

10DDN    ERROR 

DCREATE    'PATH, "namelist": UPDATE 

DFOR   T-1    TD    100 

DNAMECTJ-"" 

DNEXT   T 

DT-0 
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GLDOP 

DINPUT  "First  Name:  ".FIRST 

□EXITIF  FIRST THEN 

DCLOSE  #PATH 

DGOTO  100 

OENDEXIT 

CINPUT  "Initial:  ", INITIAL 

DINPUT  "Last:  ".LAST 

DT-T+1 

DNAMECT)-FIRST+"  "+INITIAL+"  "+LAST 

DPUT  *'PATH,NAME<T) 

GSEEK  #PATH,T*26 

DENDLDOP 

100HQPEN  #PATH,"namelist":READ 

DPR  I  NT   \  PRINT 

DPR  I  NT  "Last  name" ."First  name", "Initial* 

3REM  Print  underline  (40  characters) 

DPR  I  NT  " 

DPR  I  NT 


DSEEK    #PATH,0 

DT-0 

DWHILE    NDT(EOF(#PATH))    DO 

DGET   'PATH, NAMES 

TT-T+1 

Z!NAMES-TRIM$(NAMES) 

"X-SUBSTR<"   ".NAMES) 

DFIRST=LEFT$<NAMES,X-1 ) 

DTEMP1 =RIOHT$CNAMES,LEN(NAMES)-X+1 ) 

DINITIAL-MID$(TEMP1 ,2,1) 

"LAST«RIGHT$(TEMP1 ,LEN£TEMP1 )-3) 

DPRINT  LAST, FIRST, INITIAL 

DSEEK  #PATH,T»26 

DENDWHILE 

GCLOSE    #PATH 

ZEND 
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I RON/TROFF    Turns  on/off  trace  function 


Syntax:      TRON 
TROFF 


Function:  Turns  on  or  off  the  BASIC09  trace  mode.  When 
trace  is  turned  on  (TRON),  BASIC09  decompiles  and  displays 
each  statement  in  a  procedure  before  execution.  BASIC09  also 
displays  the  result  of  each  expression  after  evaluation.  This 
function  lets  you  follow  program  flow  and  is  helpful  in  debug- 
ging and  analyzing  the  execution  of  a  procedure,  After  the 
procedure  is  debugged,  remove  the  TRON  statement. 

If  you  want  to  view  only  a  portion  of  a  procedure's  execution, 
surround  that  portion  with  TRON  and  TROFF.  Tracing 
begins  immediately  after  the  TRON  statement  and  ends  at 
the  TROFF  statement.  The  rest  of  the  program  executes 
normally. 

Parameters:  None 

Examples: 

Bt'"eeeeeeeeeeeBBBtieeBee"*B$ 

N=1+LENCB$) 

FOR  1-4  TO  1  STEP  -1 

TRON 

N-N-4 

A<I)-VAL(MID$CB$,N,4)) 

TROFF 

NEXT  I 
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<- 


TRUE    Returns  a  Boolean  TRUE  value 


Syntax:      variable = TRUE 


Function:  TRUE  is  a  Boolean  function  that  always  returns 
True.  Tfou  can  use  TRUE  and  FALSE  to  assign  values  to  Boo- 
lean variables. 

Parameters: 

variable  The  Boolean  storage  unit  you  want  to  set  to 

True. 

Examples: 

DIM  TEST:BODLEAN 
TEST=TRUE 

Sample  Program: 

This  procedure  asks  five  questions.  If  your  answer  is  correct,  it 
stores  the  Boolean  value  TRUE  in  a  Boolean  type  variable.  If 
your  answer  is  incorrect,  it  stores  the  Boolean  value  FALSE  in 
the  variable. 

PROCEDURE  quiz 

DDIM  REPLY, VALUE ;B001EAN;  ANSWER : STRING! 1 ] ; 

QUESTIONiSTRINGtSg] 

CFOR  T-1  TO  S 

DREAD  QUESTION, VALUE 

DPRINT  QUESTION 

DPR  I  NT  "CTJ  -  TRUEZCQinKF)  =  FALSE" 

DPRINT  "Select  T  or  FiffJ"; 

DGET  *1 .ANSWER 

DIF  ANSWER-"T"  THEN 

DREPLY-TRUE 

DELSE 

DREPLY=FALSE 

DENDIF 

DIF  REPLY-VALUE  THEN 

DPRINT   \  PRINT  "That's  Correct .. .Good  Show!" 

DELSE 
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DPRINT  "Sorry,  you're  wrong .. .Better  Luck  next 

lime." 

DENDIF 

DPRINT   \  PRINT   \  PRINT 

DNEXT  T 

DDATA  "In  computer  talk,  CPU  stands  for  Central 

Packaging  Unit.",  FALSE 

DDATA  "The  actual  value  of  64K  is  6553G 

bytes.", TRUE 

GDATA  "The  bits  in  a  byte  are  normally  numbered 

through  7.", TRUE 

DDATA  "BASIC09  has  four  data  types .", FALSE 

DDATA  "The  LAND  function  is  a  Boolean  type 

operator. ".FALSE 

:end 


11-176 


BASIC09  Command  Reference  1 11 


1  Y  it Jbi    Defines  a  data  type 


Syntax:       TYPE  name  =  typedeclar  Utypedeclaxi;...]] 

Function:  Defines  new  data  types  (complex  data  structures). 
New  data  types  are  vectors  (one-dimensional  arrays)  of  previ- 
ously defined  types.  Structures  created  by  TYPE  differ  from 
arrays  in  that  they  can  consist  of  elements  of  different  types, 
and  BASIC09  accesses  elements  by  field  names  rather  than  by 
an  indexed  position. 

Parameters: 

name  The  name  you  select  for  the  new  data  type. 

typedeclar  One  or  more  type  declarations,  which  can  con- 
sist of  field  names,  type  declarations,  and  sub- 
scripts. Separate  different  types  or  different 
lengths  of  string  declarations  with  semicolons. 


Notes: 


Complex  data  structures  allow  you  to  create  data  types  that 
are  appropriate  for  a  specific  task.  You  can  organize,  read, 
and  write  associated  data  naturally.  Also,  BASIC09  estab- 
lishes and  defines  element  positions  at  compilation  time. 
This  saves  time  and  overhead  at  run  time  because 
BASIC09  can  access  the  elements  of  a  data  structure  faster 
than  it  can  access  the  elements  of  an  array. 

When  you  define  new  data  structures  using  TYPE,  you  can 
can  include  any  of  the  five  existing  data  types  (string,  real, 
integer,  byte,  and  Boolean),  or  you  can  include  data  struc- 
ture types  that  you  previously  defined  with  TYPE.  This 
means  that  your  structures  can  be  simple  or  very  complex, 
such  as  non-rectangular  data  lists  or  trees. 

TYPE  does  not  create  storage.  You  create  storage  using  the 
DIM  statement,  after  using  TYPE. 

To  access  elements  of  a  data  structure,  use  the  field  name 

as  well  as  any  appropriate  element  index. 
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For  more  information  on  creating  and  using  complex  data 
types,  see  "Complex  Data  Types"  in  Chapter  6. 


Examples: 


TYPE  LIBRARY-TITLE, AUTHOR, PUBLISHER: STRING [25] ; 
REFERENCE; INTEGER 
DIM  BOOKC500):LIBRARY 

TYPE  PARTS-ITEM, LOCATION:STRINGC20] ;  CAT:REAL; 

QUANTITY;INTEGER 

DIM    INVENTORYO000>:PARTS 

Sample  Program: 

This  procedure  builds  an  array  to  contain  a  book  reference  list, 
including  the  book  title,  the  author's  name,  the  publisher,  and  a 
reference  number.  It  does  so  by  using  TYPE  to  create  a  special 
data  structure  to  store  all  the  information  for  each  book. 

PROCEDURE  books 

CTYPE  L I BRAR Y=T I TLE, AUTHOR, PUBLISHER: STRING [30]; 

REFERENCE: INTEGER 

DDIM  BODKSC100):LIBRARY 

JT-B 

DLDOP 

□T-T+1 

DINPUT  "BOOK  TITLE. . .",BT$ 

DBOOKS(T).TITLE-BT$ 

DEXITIF  BOOKS(T). TITLE THEN 

QGOTO  100 

GENDEXIT 

DINPUT  "Book  Author. . .",BA* 

[]BOOKSCT>.  AUTHDR-BAS 

DINPUT  "Book  Publisher. . .",BPS 

CBOOKS(T>.PUBLISHER-BP$ 

GINPUT  "Reference  Number  ... ",BO0KS(T) .REFERENCE 

CENDLOOP 

100GFOR  X»1  TO  T-1 

CPRINT  BOOKSCX). TITLE;  "  ,  " ;  BOOKSCX ). AUTHOR ;  "  , 

■<  ■ 

■> 

CBOOKS(X). PUBLISHER;  "  ,  ";  BOOKSC X ). REFERENCE 

DNEXT  X 

DEND 
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UNTIL    Terminates  a  REPEAT  loop  on  specified 
condition 


Syntax:      REPEAT 

procedure  lines 
UNTIL  expression 


Function:  Ends  a  REPEAT  loop.  REPEAT  establishes  a  bop 
that  executes  the  encompassed  procedure  lines  until  the 
result  of  the  expression  following  UNTIL  is  true.  Because  the 
loop  is  tested  at  the  bottom,  the  lines  within  the  loop  are  exe- 
cuted at  least  once. 

Parameters: 

procedures         Statements  you  want  to  execute  in  the  loop. 

lines 

expression  A  Boolean  expression  (the  result  must  be 

either  True  or  False). 


Examples: 


REPEAT 

COUNT    -    COUNT+1 

UNTIL    COUNT    >    100 

INPUT   X,Y 

REPEAT 

X    =    X-1 

Y    =    Y-1 

UNTIL    X<1    DR    Y<8 

See  REPEAT  for  more  information. 
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USING    Formats  PRINT  output 


Syntax:      PRINT  [#path]  USING  [format,]  data[;data...] 


Function:  Prints  data  using  a  format  you  specify.  This  state- 
ment is  especially  useful  for  printing  report  headings, 
accounting  reports,  checks,  or  any  document  requiring  a  spe- 
cific format. 

USING  is  actually  an  extension  of  the  PRINT  statement.  The 
same  rules  that  apply  to  the  PRINT  statement  also  apply  to 
the  PRINT  USING  statement  (see  PRINT). 

Parameters: 

path  The  number  to  an  opened  device  or  file.  If  you 

do  not  specify  path  the  default  is  #1,  the  video 
screen  (standard  output  device).  To  print  to 
another  device  or  file,  first  OPEN  a  path  to 
that  file  or  device  (see  OPEN). 

format  An  expression  specifying  the  arrangement  of 

the  displayed  data. 

data  Any  numeric  or  string  constant  or  variable. 

Always  enclose  string  constants  within  quota- 
tion marks.  Separate  all  data  items  with 
semicolons  or  commas. 

See  PRINT  USING  for  more  information. 
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VAIj    Converts  string  data  to  numeric  data 


Syntax:       VAListring) 


Function:  Converts  string-type  data  to  numeric-type.  \5\L  is 
the  inverse  of  the  STR$  function.  It  returns  the  real  value 
represented  by  the  characters  in  a  string.  If  any  character  in 
the  specified  string  is  not  numeric,  BASIC09  returns  an  error. 

Parameters: 

string  An  ASCII  string  containing  one  or  more  of  the 

following  characters:  0123456789.  +  $-. 

Examples: 

PRINT  VALCI23) 

A$-"44.66" 
PRINT  VAL<A$) 

Sample  Program: 

This  procedure  calculates  an  exponential  value,  then  adds  the 
necessary  number  of  zeroes  to  convert  it  to  standard  notation,  It 
uses  STR$  to  convert  the  original  number  to  a  string,  then  uses 
\AL  to  convert  the  exponent  into  a  value  to  determine  the  cor- 
rect decimal  place. 

PROCEDURE  blgnum 

DDIM   C, PLACES, B.SlGNiSTRING;   EX  , COUNT, NENCOUNT , 

DECIMAL: INTEGER 

DDIM   NEW,2ERD,NEWEST:STR1NGM00] 

DC0UNT=-1 

nZERO*"000000000000000000000000000000000000" 

□HEW-""    \NEWEST 

DINPUT    "What    number    do    you    want    to    raise    to    the 

power    of    14?. . .",NUM 

DA=NUMA14 

DB-STR$(A> 

DEX-SUBSTR("E",B) 

DSIGN*MID$CB,EX+1  ,1) 
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DPLACES=RIGHT$(B,IENCB)~EX-1 > 

DFDR   T=1    TO    LEN(B> 

HC«!>1ID$CB,T,1) 

□IF   C-"."   THEN 

L"DECIMAL  =  0 

CGOTO    1 0 

DENDIF 

ODECIMAL-DECIMAL+1 

QIF    C-"E"   THEN    100 

DNEW-NEW+C 

10DNEXT    T 

100DNEWCDUNT-VAL<:PLACES>  -decimal 

DNEW-NEW+LEFT$(ZERO,NEWCOUNT+1  ) 

DFDR   T=LEN<NEW>    TO    1    STEP    -1 

DCOUNT=COUNT+1 

DNEWEST-MID*{NEW,T,1 >+NEWEST 

DIF   M0DCC0UNT,3)«=2   AND  T>1    THEN 

CNEWeST-","+NEWEST 

DENDIF 

DNEXT   T 

DPRINT    NUM;    "    to    the    power    of    14    = 

DPRINT    ■■-    "}    NEWEST 

DEND 
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WHILE/DO/ENDWHILE     Establishes 

a  loop 


Syntax:       WHILE  expression  DO 
procedure  lines 
ENDWHILE 


Function:  Establishes  a  loop  that  executes  the  encompassed 
procedure  lines  while  the  result  of  the  expression  following 
WHILE  is  true.  Because  the  loop  is  tested  at  the  top,  the 
lines  within  the  loop  are  never  executed  unless  the  expression 
is  true. 

Parameters: 

expression         A  Boolean  expression  (has  a  result  of  True  or 
False). 

procedure  Program  lines  to  execute  if  the  expression  is 

lines  true. 

Examples: 

WHILE  COUNT  <  1 2  DO 
COUNT  -  COUNT+1 
ENDWHILE 

Sample  Program: 

"Vbu  must  create  a  file  of  directory  names  using  the  GET  sample 
program  before  you  can  use  the  following  procedure.  Copyutil 
uses  the  filenames  created  by  the  GET  sample  program  to  copy  a 
directory's  files  to  another  directory  you  specify.  %u  must  spec- 
ify a  directory  name  that  does  not  exist.  Copyutil  uses  a 
WHILE/DO/ENDWHILE  loop  to  continue  copying  until  BASIC09 
reaches  the  end  of  the  file. 
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PROCEDURE  copyutil 

DDIM  PATH, T.COUNT: INTEGER;  FI LE , JOB ,D I RNAME : STR I NG 

DOPEN  #PATH/,dlrflle";READ 

DINPUT  "Name  of  new  directory. .." .DIRNAME 

DSHELL  "MAKDIR  "♦DIRNAME 

DSHELL  "LOAD  COPY" 

□WHILE  NOTCEOFOPATH))  DO 

DREAD  #PATH,FILE 

DJOB-FILE+"  "*DIRNAME+"/"+FILE 

DON   ERROR   GOTO    1 0 


DPRINT  "COPY 

";  JOB 

DSHELL  "COPY 

"  +  JOB 

10DON  ERROR 

DENDWHILE 

DCLOSE  #PATH 

XND 
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W  Xvl  1  hi     Writes  data  to  a  sequential  file  or 
device 


Syntax:      WRITE  Wpath,]  data 

Function:  Writes  an  ASCII  record  to  a  sequential  file  or  to  a 
device. 

Parameters: 

path  A  variable  containing  the  path  number  of  the 

file  or  device  to  which  you  want  to  send  data. 
Path  can  be  one  of  the  the  standard  I/O  paths 
(0,  1,  2). 

cfoto  The  data  you  want  to  send  over  the  specified 

path. 

Notes: 

The  following  information  deals  with  writing  sequential  disk 
files: 

•  To  write  file  records,  you  must  first  dimension  a  variable  to 
contain  the  path  number  of  the  file,  then  use  OPEN  or 
CREATE  to  open  a  file  in  the  WRITE  or  UPDATE  access 
mode. 

•  Records  can  be  of  any  length  within  a  file. 

•  Individual  data  items  in  the  input  record  are  separated  by 
ASCII  null  characters.  You  can  also  separate  numeric  items 
with  comma  or  space  character  delimiters.  Each  input 
record  is  terminated  by  a  carriage  return  character. 

Examples: 

WRITE    #PATH,DATA$ 
WRITE    #1 , RESPONSES 
WRITE    *0UTPUT,INDEX(X> 
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OPEN    #PATH,"namef lie": WRITE 

FDR   T=1    TO    10 

READ   NAME$ 

WRITE    #PATH,    NAME$ 

NEXT   T 

CLOSE   'PATH 

DATA    "JIM" , "JOE" , "SUE" ,"TI NA" , "WENDY" 

DATA    "SALL" , "MICK  I E" , "FRED" , "MARV" , "WINN  I E" 

Sample  Program: 

This  procedure  selects  100  random  values  between  1  and  10.  It 
uses  WRITE  to  place  the  values  into  a  disk  file.  Next,  it  reads 
the  values  from  the  file  and  uses  asterisks  to  indicate  how  many 
times  RND  selected  each  value. 

PROCEDURE  randliat 

DDIM  SHOW,BUCKET:STRING 

DDIM  T, PATH, SELECTC1 0) ,R: INTEGER 

OBUCKET*" * ********»»»«******#*»**" 

DFOR  T-1  TO  10 

DSELECTCTJ-0 

DNEXT   T 

DON    ERROR    GOTO    10 

DSHELL    "DEL    RANDFILE" 

10u   ON   ERROR 

DCREATE   #PATH , "randf i le" : UPDATE 

DFOR   T-1    TO    100 

0R-RND<9>*1 

DWRITE    #PATH,R 

DNEXT   T 

DPRINT  "Random  Diatribut ion" 

OSEEK  #PATH,0 

DFOR  T-1  TO  100 

DREAD  *PATH,NUM 

DSELECT<NUMJ-SELECT<NUM)+1 

DNEXT  T 

DFOR  T-1  TO  10 

DSHDW-RIGHT$CBUCKET,SELECT(T)> 

DPRINT  USING  "S6<,I3<,S2<,S20<", "Number", T,":", 

SHOW 

DNEXT  T 

GCLOSE    #PATH 

ZEND 
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AaJXx    Returns  the  exclusive  OR  of  two  values 


Syntax:       operandi  XOR  operand2 


Function:  Performs  the  logical  exclusive  OR  operation  on  two 
or  more  values,  returning  a  value  of  either  TRUE  or  FALSE. 

Parameters: 

operandi  Boolean  values  or  expressions  (that  result  in 

operand2  values  of  True  or  False). 

Examples: 

PRINT  A>2  XOR  B>3 

PRINT  A$-"YES"  XOR  B$-"YES" 

Sample  Program: 

This  procedure  lets  two  people  type  numbers  until  one  of  them 
guesses  the  number  that  the  computer  picks.  It  uses  XOR  to 
determine  that  one  of  the  numbers  typed  is  the  correct  number, 
but  not  both. 

PROCEDURE  drawstraw 

jDIM  NUM1 ,NUM2,R: INTEGER;  A:B00LEAN 

DPRINT  "This  program  will  help  you  pick" 

DPRINT  "between  two  people.  Choose  who  will  be" 

DPRINT  "Person  1  and  who  will  be  Person  2." 

DPRINT  "Then,  enter  numbers  between  1  and  10" 

CPRINT  "when  requested." 

DPRINT 

DR  =  RND£1  0) 

10DINPUT  "Person  1,  type  a  number  and  press 

ENTER. . .",NUM1 

QINPUT  "Person  2,  type  a  number  and  press 

ENTER. . .",NUM2 

DA-NUM1-R  XQR  NUM2-R 

DIF  A=FALSE  THEN 

DPRINT  "You'll  have  to  try  again..." 

DPRINT 
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CGOTO  10 

CENDIF 

DIF  NUM1=R  THEN 

jPRINT  "You  win,  Person  11 

DENDIF 

DIF  NUM2=R  THEN 

HPRINT  "You  win,  Person  2' 

QENDIF 

DPRINT   "The    Number    wag.,. 

DEND 
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Program  Optimization 


BASIC09's  multipass  compiler  produces  a  compressed  and  optim- 
ized low-level  I-code  for  execution.  Compared  to  other  BASIC  lan- 
guages, BASIC09  greatly  decreases  both  the  storage  space 
required  for  program  code  and  the  execution  speed  of  programs. 

Because  BASIC09  produces  I-code  at  a  powerful  level,  it  can 

handle  numerous  MPU  (micro  processor  unit)  instructions  with  a 
single  interpretation.  Therefore,  for  complex  programs,  there  is 
little  performance  difference  between  the  execution  of  I-code  and 
pure  machine-language  instructions. 

Most  BASIC  languages  have  to  compile  from  text  as  they  run,  or 
search  tables  of  tokens  in  order  to  execute  code.  Instead, 
BASIC09  I-code  instructions  contain  direct  references  to  vari- 
ables, statements,  and  labels.  BASIC09  fully  utilizes  the  power  of 
the  6809  instruction  set,  as  well,  which  is  optimized  for  efficient 
execution  of  compiler-produced  code. 

Because  BASIC09  interprets  I-code,  you  have  a  variety  of  entry- 
time  and  run-time  tests  and  development  aids.  The  editor  reports 
syntax  errors  immediately  when  they  are  entered.  The  debugger 
lets  you  debug  using  original  program  source  statements  and 
names.  The  I-code  interpreter  performs  run-time  error  checking 
of  array  structures  and  BASIC09  functions. 

Optimum  Use  of  Numeric  Data  Types 

The  following  notes  apply  to  the  use  of  BASIC09  numeric  data 
types: 

•  BASIC09  includes  several  different  numeric  representa- 
tions (real,  integer,  byte),  and  performs  automatic  type 
conversions  between  them.  This  means  that  without 
care,  your  code  might  contain  expressions  or  loops  that 
take  more  than  ten  times  longer  to  execute  than  is 
necessary. 
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Some  BASIC09  numeric  operators,  such  as  +  ,-,*,  and  /, 
and  some  BASIC09  control  structures  include  versions  for 
both  real  and  integer  values.  Integer  versions  execute 
much  fester  and  can  have  slightly  different  properties. 
For  instance,  integer  division  discards  any  remainder. 

Integer  operations  are  fester  because  they  use  corre- 
sponding 6809  instructions.  Using  integers  increases 
speed  and  decreases  storage  requirements.  Integer  opera- 
tions use  the  same  symbols  as  real  operations,  but 
BASIC09  automatically  selects  the  integer  operations 
when  when  all  operands  of  an  expression  are  of  byte  or 
integer  type. 

Type  conversion  takes  time.  Using  expressions  with  oper- 
ands and  operators  of  the  same  kind  is  most  efficient. 

BASIC09's  real  (floating  point)  math  provides  excellent 
performance.  It  includes  a  40-bit  binary  floating  point 
representation  and  uses  the  CORDIC  technique  to  derive 
all  transcendental  functions.  This  integer  shift-and-add 
technique  is  faster  and  more  consistent  than  the  common 
series-expansion  approximations. 

■  At  times,  you  can  obtain  similar  or  identical  results  in  a 
number  of  different  ways  and  at  different  execution 
speeds.  For  example,  if  the  variable  Value  is  an  integer, 
then  Value* 2  is  a  fast  integer  operation.  However,  if  the 
expression  is  Volue«2.0,  2.0  is  represented  as  a  real 
number  and  the  operation  requires  real  multiplication. 
BASIC09  must  transform  the  integer  Value  into  a  real 
value.  If  the  result  of  the  expression  is  assigned  to  an 
integer  type  variable,  BASIC09  must  transform  the 
result  back  to  an  integer  type.  The  decimal  point  can 
slow  the  operation  by  about  ten  times. 
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Arithmetic  Functions  Ranked  by  Speed 

Typical  Speed 

Operation 

in  MPU  Cycles 

Integer  add  or  subtract 

150 

Integer  multiply 

240 

Real  add 

440 

Real  subtract 

540 

Integer  divide 

960 

Real  multiply 

990 

Real  divide 

3870 

Real  square  root 

7360 

Real  logarithm  or  exponential 

20400 

Real  sine  or  cosine 

32500 

Real  power 

39200 

Referring  to  the  previous  table  can  help  you  in  your  program- 
ming. For  instance,  notice  that  it  is  quicker  to  add  a  value  to 
itself  rather  than  multiplying  it  by  2.  Similarly,  multiplying  a 
value  by  itself  or  using  SQ  on  a  value  is  much  faster  than  rais- 
ing a  value  to  the  power  of  2. 

Notice  that  a  real  divide  takes  3870  cycles,  while  a  real  multipli- 
cation takes  only  990  cycles.  Multiplying  a  value  by  0.5  is  four 
times  quicker  than  dividing  the  value  by  2. 

Quicker  Loops 

BASIC09  has  two  versions  of  FOR/NEXT  loops,  one  for  integer 
loop  counter  variables  and  one  for  real  loop  counter  variables.  It 
automatically  uses  the  appropriate  version.  Integer  FOR/NEXT 
loops  are  much  faster  than  real  FOR/NEXT  loops. 

Other  kinds  of  loops  also  run  faster  if  you  use  integer  type  vari- 
ables for  the  loop  counters.  When  writing  program  loops,  remem- 
ber that  statements  inside  the  loop  can  execute  many  times  for 
each  execution  outside  the  loop.  Whenever  possible,  compute  val- 
ues before  entering  loops. 
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Arrays  and  Data  Structures 

The  internal  workings  of  BASIC09  use  integer  numbers  to  index 
arrays  and  complex  data  structures.  This  means  that  BASIC09 
must  convert  real  type  variable  or  expression  subscripts  before  it 
can  handle  them.  Using  integer  expressions  for  subscripts 
increases  execution  speed. 

Using  the  assignment  statement  LET  to  copy  identically  sized 
data  structures  is  much  faster  than  copying  arrays  or  structures 
element-by-element  inside  a  loop. 

The  PACK  Command 

PACK  causes  a  second  compilation  of  a  specified  procedure. 
Depending  on  such  variables  as  the  number  of  procedure  com- 
ments and  the  inclusion  of  line  numbers,  packed  procedures  exe- 
cute from  10  to  30  percent  faster.  Line  numbers  cause  unpacked 
procedures  to  run  slower. 

Minimizing  Constant  Expressions 
and  Subexpressions 

For  maximum  execution  speed,  precalculate  constant  expres- 
sions. For  instance,  x  -  x  +  5  produces  the  same  result  as  x  - 
x*sqrt<100)/2.  However,  the  first  expression  requires  approxi- 
mately 150  MPU  cycles  while  the  second  expression  requires 
11,650  MPU  cycles.  If  you  use  such  an  expression  inside  a  loop, 
the  additional  execution  time  is  enormous. 


Input  and  Output 


Accessing  data  one  line  or  record  at  a  time  is  much  faster  than 
accessing  it  one  character  at  a  time,  Also,  the  GET  and  PUT 
statements  are  much  faster  than  READ  and  WRITE  statements 
when  accessing  disk  files.  This  is  because  GET  and  PUT  use  the 
same  binary  format  as  BASIC09's  internal  operations.  READ, 
WRITE,  PRINT,  and  INPUT  must  perform  binary-to-ASCII  or 
ASCII-to-binary  conversions,  which  take  more  time. 
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Error  Codes 

Signal  Errors 

Code 

Meaning 

1 

Unconditional  termination 

2 

Keyboard  termination 

3 

Keyboard  interrupt 

BASIC09  Error  Codes 

Code 

Meaning 

10 

Unrecognized  symbol 

11 

Excessive  verbiage 

12 

Illegal  statement  construction 

13 

I-code  overflow,  need  more  workspace  memory 

14 

Illegal  channel  reference,  bad  path  number  given 

15 

Illegal  mode  (read/write/update)  -  directory  only 

16 

Illegal  number 

17 

Illegal  prefix 

18 

Illegal  operand 

19 

Illegal  operator 

20 

Illegal  record  field  name 

21 

Illegal  dimension 

22 

Illegal  literal 

23 

Illegal  relational 

24 

Illegal  type  suffix 

25 

Too-large  dimension 

26 

Too-large  line  number 

27 

Missing  assignment  statement 

28 

Missing  path  number 

29 

Missing  comma 

30 

Missing  dimension 

31 

Missing  DO  statement 

32 

Memory  full,  need  more  workspace  memory 

33 

Missing  GOTO 

34 

Missing  left  parenthesis 

35 

Missing  line  reference 

36 

Missing  operand 

37 

Missing  right  parenthesis 

38 

Missing  THEN  statement 

39 

Missing  TO 
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Code      Meaning 


40  Missing  variable  reference 

41  No  ending  quote 

42  Too  many  subscripts 

43  Unknown  procedure 

44  Multiply-defined  procedure 

45  Divide  by  zero 

46  Operand  type  mismatch 

47  String  stack  overflow 

48  Unimplemented  routine 

49  Undefined  variable 

50  Floating  overflow 

51  Line  with  compiler  error 

52  Value  out  of  range  for  destination 

53  Subroutine  stack  overflow 

54  Subroutine  stack  underflow 

55  Subscript  out  of  range 

56  Parameter  error 

57  System  stack  overflow 

58  I/O  type  mismatch 

59  I/O  numeric  input  format  bad 

60  I/O  conversion:  number  out  of  range 

61  Illegal  input  format 

62  I/O  format  repeat  error 

63  I/O  format  syntax  error 

64  Illegal  path  number 

65  Wong  number  of  subscripts 

66  Non-record-type  operand 

67  Illegal  argument 

68  Illegal  control  structure 

69  Unmatched  control  structure 

70  Illegal  FOR  variable 

71  Illegal  expression  type 

72  Illegal  declarative  statement 

73  Array  size  overflow 

74  Undefined  line  number 

75  Multiply-defined  line  number 

76  Multiply-defined  variable 

77  Illegal  input  variable 

78  Seek  out  of  range 

79  Missing  data  statement 


A-2 


Error  Codes  I A 


Windowing  and  System  Errors 

Code      Meaning 


183 

Illegal  window  type 

184 

Window  already  defined 

185 

Font  not  found 

186 

Stack  overflow 

187 

Illegal  argument 

188 

(unused) 

189 

Illegal  coordinates 

190 

Internal  integrity  check 

191 

Buffer  size  is  too  small 

192 

Illegal  command 

193 

Screen  or  window  table  is  full 

194 

Bad/undefined  buffer  number 

195 

Illegal  window  definition 

196 

Window  undefined 

197 

(unused) 

198 

(unused) 

199 

(unused) 

200 

Path  table  full 

201 

Illegal  path  number 

202 

Interrupt  polling  table  full 

203 

Illegal  mode 

204 

Device  table  full 

205 

Illegal  module  header 

206 

Module  directory  full 

207 

Memory  full 

208 

Illegal  service  request 

209 

Module  busy 

210 

Boundary  error 

211 

End  of  file 

212 

Returning  non-allocated  memory 

213 

Non-existing  segment 

214 

No  permission 

215 

Bad  path  name 

216 

Path  name  not  found 

217 

Segment  list  full 

218 

File  already  exists 

219 

Illegal  block  address 

220 

Phone  hangup  data  carrier  detect  lost 

221 

Module  not  found 

223 

Suicide  attempt 
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Code       Meaning 


224  Illegal  process  number 

226  No  children,  can't  wait  for  nonexistent  child  process 

227  Illegal  SWI  code 

228  Process  aborted,  signal  2 

229  Process  table  full,  can't  fork  a  process 

230  Illegal  parameter  area 

231  Known  module 

232  Incorrect  module  CRC 

233  Signal  error 

234  Non-exi9tent  module 

235  Bad  name 

237  System  RAM  full 

238  Unknown  process  ID 

239  No  task  number  available 

240  Illegal  unit  error 

241  Bad  sector  number 

242  Write  protected  disk 

243  CRC  error 

244  Read  error 

245  Write  error 

246  Not  ready,  device  not  ready 

247  Seek  error 

248  Media  full 

249  Wrong  type,  incompatible  media  type 

250  Device  busy 

251  Disk  ID  change,  disk  changed  with  open  files 

252  Record  is  locked  out 

253  Non-sharable  file  busy 
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The  Inkey  Program 


Assembly  Language  Listing  of  Inkey 

An  assembled  version  of  Inkey  is  included  on  the  CONFIG/ 
BASIC09  diskette.  Use  Inkey  from  BASIC09  with  the  RUN 
statement, 

■  »»<»»»<«  t  If  MIMlUMt 

'  INKE1  -  a  subroutine  for  BASIC19  by  Robert  Doggett 

•  Called  by:  RUN  INKEYJStrVar) 

»  JUN  INKEY<Path,StrVar) 

»  INKEY  determines  if  a  key  has  been  typed  on  the  given  path 

•  (Standard  Input  if  not  specified),  and  if  so,  returns  the  next 

•  character  in  the  String  variable.  If  no  key  has  been  typed,  the 

•  null  string  is  returned.  If  a  path  is  specified,  it  lust  be 

•  either  type  BYTE  or  INTEGER. 


NAM 

INKEY 

1FP1 

USE 

/DI7DEFS/D59DEFS 

ENDC 

0021 

TYPE 

set 

SBRTN«DBJCT 

1)81 

REVS 

set 

REENT'1 

mi 

87CD885E 

mod 

InKeyEnd, 
, InKeyEnt 

InKeyNam, TYPE, REVS 
,  SIZE 

im> 

436ESB6S 

InKcyNsm  fcs 

"Inkey" 

d  im 

org 

1 

Parameters 

D  mi 

Return 

rmb 

2 

Return  addr  of  caller 

D  8182 

PCount 

rirb 

2 

Num  of  parains  followini 

d  im 

Paraml 

rmb 

2 

1st  param  adcfr 

D  1MB 

Lengthl 

rmb 

2 

size 

D  8888 

Param2 

rmb 

2 

2nd  pararn  addr 

D  888ft 

Length? 

rmb 

2 

size 

888C 

EtParam 

equ 

J3B 

888E 

SIZE 

eqy 

* 

801? 

3064 

InKeyEnt 

.  leax 

Paraml ,5 
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8814 

EC62 

ldd 

Pcount,5 

Get  parameter  count 

8816 

18838881 

cfflpd 

t\ 

just  one  parameter? 

881A 

2727 

beq 

InKey26 

..res;  default  path  A-l 

881C 

18838882 

cmpd 

rt 

Are  there  two  params? 

8828 

263S 

hut 

ParamErr 

No,  abort 

8822 

ECF864 

idd 

IParam1,Sl 

Get  path  number 

8825 

AE66 

ldx 

Length!  ,S 

8827 

381F 

leax 

-1,K 

byte  variable? 

8829 

2786 

beq 

InKeyl B 

..Yes;  (A)'Path  number 

882B 

381F 

ICBX 

■1,1 

Integer? 

SB2D 

2628 

bne 

ParamErr 

..No;  abort 

8B2F 

1F98 

tfr 

B,A 

8831 

3868 

InKeylS 

leax 

Param2,S 

8833 

EE82 

InKey2l 

Idu 

1,1 

length  of  string 

883S 

AE84 

ldx 

1,1 

addr  of  string 

8837 

C6FF 

ldb 

#$FF 

8839 

E784 

stb 

1,1 

Initialize  to  null  sir 

BOB 

11838882 

CfllpU 

'2 

at  least  two-byte  a tr? 

883F 

2S82 

bio 

Msy38 

..No 

88-11 

E7B1 

stb 

1,1 

put  str  terminator 

8843 

C681 

In<ey30 

ldb 

'SS. Ready 

8845 

183F8D 

0S9 

ISGetStt 

is  there  any  data  reedy? 

8848 

2588 

bcs 

InKeySS 

..No;  exit 

884A 

188E8881 

Idy 

#1 

884E 

183F89 

0S9 

IiRcod 

Read  one  byte 

8851 

39 

rta 

returns  error  status 

8852 

C1F6 

lnKey9B 

cuipb 

»£$NotRdy 

8854 

2683 

bne 

InKeyErr 

8856 

39 

rta 

(carry  clear) 

8857 

C638 

ParamErr 

ldb 

CESParam 

Parameter  Error 

8859 

43 

InKeyErr 

coma 

88SA 

39 

rts 

8ISB 

1A6916 

emod 

88SE 

inKeyEnd 

:  equ 

« 
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Index 

ABS  command    11-4 

ASC  command    11-9 

absolute  value    11-4 

ASCII 

accessing 

character  value    11-18 

files    8-1,  10-8 

codes    9-1  -  9-6, 11-9 

lines  (editor)    4-4  -  4-5 

ASN  command     11-10 

OS-9  commands  from 

assign 

BASIC    3-7 

variable  storage    11-31 

ACS  command     11-5 

variable  values    11-78 

adding  lines    4-10  -  4-12 

variables  (debug)    5-3 

addition    7-3  -  7-4 

ATN  command    11-11 

ADDR  command    11-6 

auto  execution    3-8 

address 

automatic  error  checking    1-4 

of  variable    6-8,  11-6 

space    11-6 

background  color 

advantages  of  BASIC09    1-1- 

high-resolution    9-34 

1-2 

medium-resolution    9-11 

ALPHA  (medium-res)    9-9, 

backslash     1-6 

9-13 

BAR  command  (high-res) 

alphanumeric 

9-52  -  9-53 

mode    9-10 

base  10  logarithm    11-83 

screen    9-9,  9-13,  9-30 

BASE  command    11-12  - 

ALT  key    1-6,9-4 

11-13 

AND 

BASIC09 

command     11-8 

advantages     1-1  -  1-2 

logical  AND 

graphics  with  128K 

command    11-84 

9-37  -  9-39 

operator    7-3,  7-4,  7-7 

quitting    1-5, 3-1 

appending 

starting    1-2  - 1-4 

data  to  files    8-3 

starting  windows 

strings    7-6 

from    9-39-9-41 

ARC  command  (high-res) 

beep    9-54 

9-50 

beginning  debug    5-1 

arccosine    11-5 

BELL  command  (high-res) 

arcsine    11-10 

9-54 

arctangent    11-11 

binary  data  record    11-58 

arithmetic 

BLNKDPF  command  (high- 

function  speed    12-2 

res)    9-55 

operators    7-3 

BLNKDN  command  (high- 

array    6-9-6-13 

res)    9-55 

address    11-6 

BOLDSW  command  (high- 

element    6-9 

res)    9-56 

index     11-12 

with  random  access 

files    8-9 

1 
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Boolean 

data    6-1  -  6-2,  6-5 

functions    7-10 

OR    11-106 

TRUE    11-175  - 11-176 

value    11-51 

border  color  (high-res)    9-58, 
9-65 

BORDER  command  (high- 
res)    9-58 

BOX  command    9-60-9-61 

brace  characters    1-6 

BREAK 

command  (debug)    5-2 
key    1-6,5-2 

breakpoint  (debug)    5-2 

buffer 

defining    9-78 
font  (high-res)    9-94 
get/put  (high-res)    9-117 
group  (high-res)    9-101 
pattern  (high-res)    9-111 

button,  joystick  (medium- 
res)    9-9,  9-22 

BYE  command    1-5,  3-1,  10-9, 
11-14 

byte 

data  type    6-1  -  6-2 
numeric  range    6-2 
retrieval  from  a  file    8-5 
type  functions    7-9 

calculate 

low-res  characters    9-5 
sine     11-154 
square  root    11-158 

call  a  shell  command    10-9 

carriage  return    1-7 

high-resolution    9-67 

CHAIN  command     11-15  - 
11-16 

changing 

a  procedure  name    10-9 
color  (high-res)     9-65  - 
9-66 


changing  (cont'd) 

color  (medium-res)    9-9 
directory    3-1,  3-7,  10-9, 

11-17, 11-19 
file  pointer    11-148 
procedures    1-4 
scale  (high-res)    9-121  - 

9-122 
text    4-7-4-9 
text  (editor)    4-1  -  4-2 
working  area  (high-res) 
9-76 
character 

backslash    1-6 
blink  (high-res)    9-55 
braces    1-6 
brackets    1-6 
fonts    9-43  -  9-44 
graphic    1-6 

high-resolution    9-8,  9-94 
reverse  video  (high- 
res)    9-120 
tilde    1-6 
underline  (high-res) 

9-126 
underscore    1-6 
up  arrow    1-6 
value    11-18 
vertical  bar    1-6 
CHD  command    3-1,  3-7, 

10-9,  11-17,  11-19 
CHX  command    3-1,3-7, 

10-9,  11-17  -  11-19 
CIRCLE     . 

high-resolution    9-62 
medium-resolution    9-9, 
9-15  -  9-16 
CLEAR 

high-resolution    9-64 
key    1-6 

medium  resolution    9-9, 
9-17 
close  a  window  (high-res) 
9-83  -  9-84 


Index 


CLOSE  command     11-20  - 
11-21 

ASCII    9-1  -  9-6,  11-9 
error    11-43,  Al  -  A4 
COLOR 

high-resolution    9-65 
medium  resolution    9-9, 
9-18,  9-19 
color 

codes  (medium-res) 

9-10  -  9-11 
default  9-79 
high-resolution    9-31, 

9-109  -  9-110 
medium-resolution    9-11 
of  border  (high-res) 

9-58  -  9-59 
of  pixel  (medium-res) 

9-28  -  9-29 
of  screen  (medium- 
res)    9-26 
palette  default    9-79 
set  (medium-res)    9-18  - 
9-19 
command 

interpreter    3-1 
line  storage  area    3-3 
line  symbols    11-2 
lines  using  spaces    2-2 
mode    1-3 

mode  reference    10-9 
commands 

by  type     10-7 
configuring  (high-res) 

9-47 
debug     10-11 
drawing  (high-res)    9-46 
editing    10-10 
executing  OS-9    3-7-3-8 
font  (high-res)    9-49 
quick  reference    10-1  - 

10-6 
system    3-1 


commands  {cont'd) 

text/cursor  (high-res) 

9-48 
using  wildcards    3-5 
window  (high-res)    9-45 
comments  in  a  procedure 

11-135  - 11-136 
compile  procedure    3-1,  3-8  - 

3-9,  10-9 
compiler,  multipass    12-1 
compiling 

procedures    1-5 
saving  space    1-2 
complement,  logical     11-96 
complex 

data  structure    1-2, 
8-11  -  8-12,  11-177  - 
11-178 
data  types    6-1,  6-13  - 
6-16 
compressed  procedures    12-1 
concatenation    7-3 
condensed  procedures    3-1 
configuring  commands  (high- 
res)    9-47 
constant  expressions    12-4 
constants,  string    6-7 
control  key    1-6 
converting 

data  types    6-6,  7-2 
numeric  types    11-54, 

11-71,  11-162  -  11-163 
string  data    11-181  - 
11-183 
copying  structure  elements 

6-16 
COS  command    11-22 
cosine    11-22 
create 

data  types    11-177 
overlay  windows  (high- 
res)    9-107 
procedures    2-1 
random  access  files    8-6  - 
8-9 
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create  (cont'd) 

sentences  procedure    4-3 
sequential  files    8-2  -  8-3 
windows    9-35  -  9-36 
CREATE  command    8-2  -  8-3, 

8-6  -  8-7,  11-23  -  11-24 
CRRTN  command  (high- 
res)    9-67 
CTRL  key    1-6  - 1-7 
CTRL-BREAK  key 

sequence    1-6,  3-1 
CURDWN  command  (high- 
res)    9-68 
CURHOME  command    9-69 
CURLFT  command  (high- 
res)    9-70 
CUROFF  command  (high- 
res)    9-71 
CURON  command  (high- 
res)    9-72 
current  command  line    1-7 
CURRGT  command  (high- 
res)    9-73 
cursor 

graphics  (high-res)     9-95, 

9-119 
graphics  (medium- 
res)    9-27 
invisible  (high-res)    9-71 
movement  1-6,  9-67  - 

9-68,  9-74  -  9-75 
position     11-116 
CURUP  command  (high- 
res)    9-74 
CURXY  command  (high- 
res)    9-75 
CWAREA  command  (high-res) 
9-76  -  9-77 


data 


changing  in  sequential 

file     8-4 
complex  types    6-1, 

6-13  -  6-16 

constants    6-6  -  6-7 


data  (cont'd) 

directory    3-7 
items    6-1 

manipulation    7-1  -  7-2 
meaning    6-1 
pointer     11-140 
reading    11-132  -  11-133 
structure    1-2,  11-177  - 

11-178,  12-2 
structure  address    11-6 
to  files    8-1 
type,  Boolean    6-5 
type,  byte    6-2 
type,  conversion    7-2 
type,  integer    6-3 
type,  real    6-3  -  6-4 
types    6-1,10-8,11-177- 

11-178, 12-1 
types,  creating    11-177  - 

11-178 
DATA  command    11-25- 

11-26 
DATE$  command     11-27  - 

11-28 
day    11-27 
deallocate 

buffer  (high-res)    9-101  - 

9-102 
graphics  memory    9-30 
windows  (high-res) 

9-83  -  9-84 
debug 

beginning  5-1 
breakpoint  5-2 
commands    5-2  -  5-4, 

10-11 
display  procedure    5-3 
quitting    5-3 
starting    5-1,  5-4  -  5-5, 

11-112 
tracing    5-4 
debug  command 
$    5-2 

BREAK    5-2 
CONT    5-2 


Index 


debug  command  (cont'd) 

DEG    5-2 

DIR    5-3 

LET    5-3 

LIST    5-3 

PRINT  5-3 

Q    5-3 

RAD    5-2 

STATE    5-3 

STEP    5-4 

TROFF    5-4 

TRON    5-4 
default  colors    9-79 
DEFBUFF  command  (high- 
res)    9-78 
DEFCOL  command  (high- 
res)    9-79 
define  a  window  (high-res) 

9-86  -  9-87 
defining  string  variables    6-4 
DEG  command     11-29 
degrees,  selecting  in  debug 

5-2,  11-29 
DELETE  command    11-30 
delete  line    1-6,  2-2 

editor    4-2 

high-resolution    9-80, 
9-92 
deleting 

procedure  lines    4-6  -  4-7 

procedures    3-6 
delimiter    4-8 

in  sequential  files    8-2 

symbols  (editor)    4-8 
DELLIN  command  (high- 
res)    9-80 
device  path    11-104 
DIM  command    11-31  -  11-32 
DIM  statement    6-2,  11-31 
DIR 

command     3-1  -3-2,  10-9 

debug    5-3 

file  access    8-1 


directory 

change    3-1,3-7,11-17, 
11-19 

data    3-7 

execution    3-7 

ROOT    3-7 
disassembled  procedure    3-3 
disk  file    8-1 

creation    11-23 

deletion     11-30 
display 

a  formatted  listing    10-9 

a  window     1-6,  (high- 
res)     9-123  -  9-124 

clearing  (medium- 
res)    9-17 

current  command 
line    1-7 

last  line     1-7 

previous  window     1-6 

procedure    3-1 

procedure  from  debug 
5-3 

procedure 

information    3-1,  10-9 

text    11-119  -  11-120 

workspace  size    3-1,  10-9 
division    7-3 

remainder    11-93 
DO  command    11-34 
dot,  graphics  (medium-res) 

9-28  -  9-29 
draw 

a  circle  (high-res)    9-62  - 
9-63 

a  circle  (medium-res) 
9-9,  9-15  -  9-16 

a  line  (high-res)     9-103  - 
9-104 

an  ellipse    9-88  -  9-89 

arcs  (high-res)    9-50  - 
9-51 

command  (high-res) 
9-46,  9-81  -  9-82 

pointer  (high-res)    9-125 
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draw  {cont'd) 

pointer  (medium-res) 

9-12 
lines  (medium-res) 

9-24  -  9-25,  9-103 
rectangles  (high-res) 
9-52  -  9-53,  9-60  -  9-61 
DWEND  command  (high- 
res)    9-83  -  9-84 
DWPROTSW  command  (high- 
res)    9-85 
DWSET  command  (high- 
res)    9-86  -  9-87 

edit 

compiler    3-1 
mode,  entering    1-4 
pointer    4-1 
terminating    2-3 
EDIT  command    3-1,  10-9  - 

10-10 
editor    4-1  -  4-9 
element    6-9 
elements 

of  a  structure, 

copying     6-16 
of  an  array    6-9 
ELLIPSE  command  (high- 
res)    9-88  -  9-89 
ELSE  command    11-35 
END  command    11-36  - 11-37 
end  execution    11-14 
end-of-file 

message    1-6 
test    11-42 
ENDEXIT  command    11-38 
ENDIP  command    11-39 
ENDLOOP  command    11-40 
ENDWHILE    11-41 
ENTER 

command  (editor)    4-1 
in  the  editor    4-4 
key    1-7 


entering 

debug    5-4  -  5-5 
the  edit  mode    1-4 
EOF  command    11-42 
equal  operator    7-5 
erase 

a  disk  file     11-30 
procedures    3-1,  11-72 
to  end  of  line    9-90 
to  end  of  window    9-91 
EREOLINE  command  (high- 
res)    9-90 
EREOWNDW  command  (high- 
res)    9-91 
ERLINE  command  (high- 
res)    9-92 
ERR  command    11-43  -  11-44 
error 

checking,  automatic    1-4 
code    11-43  -  11-44, 

A-l  -  A-4 
in  a  program  line    2-2 
simulation    11-45  -  11-46 
trapping    11-97  -  11-99 
ERROR  command    11-45 
escape  function    1-6 
establishing  a  window    9-32, 

9-41,    9-86-9-87 
evaluating  expressions    7-1  - 

7-2 
evaluation,  order  of 

operators    7-4  -  7-5 
examine 

a  procedure    4-4 
memory    11-113 
exclusive  OR    11-187  -  11-188 
EXEC  file  access    8-1 
executable  procedures    3-8 
execute 

a  procedure    2-3,  3-1, 
3-8,  10-9, 
11-145  -  11-147 
an  OS-9  command    3-1, 
3-7  -  3-8 


Index 


execute  (cont'd) 

modules    11-15  - 11-16 

procedure  lines    11-34 
execution 

automatic    3-8  -  3-9 

directory  change    3-1, 
3-7 

speed    1-1 

stepping    5-5  -  5-6 

stopping    11-161 

termination     11-14 
EXITIF/THEN/ENDEXIT 

commands     11-47 
exiting 

BASIC09     1-5 

debug    5-3 
EXP  command    11-50 
exponent,  natural     11-50 
exponentiation    7-3 
expression    7-1 

FALSE 

command     11-51  -  11-52 
value    7-7 

faster  loops    12-2 
file 

listing  procedures  to    3-4 
path     11-104 
pointer    8-3,  8-5, 

11-148  -  11-149 
pointer,  rewinding    8-11 
retrieving  bytes    8-5 
writing    11-129  - 

11-  130,  11-185- 

11-186 
files    8-1 

accessing    8-1,  10-8 
appending  data    8-3 
closing    11-20  -  11-21 
creating  random 

access    8-6  -  8-9 
creating  sequential    8-2  - 

8-4 
creation    11-23  -  11-24 
opening     11-104  -  11-105 


files  (cont'd) 

random  access    8-5  - 

8-11 
writing  to     8-3 
FILL  command  (high-res) 

9-93 
filled  rectangles  (high-res) 

9-52  -  9-53 
finding 

graphics  screen  (medium- 
res)    9-20-9-21 
lines    4-5 
fire  button  (medium-res)     9-22 
FIX  command    11-53 
FLOAT  command    11-54 
FONT  command  (high-res) 

9-94 
font-handling  commands  (high- 
res)    9-49 
fonts    9-43  -  9-44 
FOR/NEXT  loops    11-159  - 

11-160 
FOR/NEXT/STEP 

commands    11-55  -  11-57 
foreground  color 

high  resolution     9-65  - 

9-66 
medium  resolution    9-11, 
9-18  -  9-19 
fork  a  shell    11-152  - 11-153 

to  a  window    9-32 
format 

medium  resolution    9-10 
of  screen  (medium- 
res)    9-26 
of  windows    9-34 
formatted  procedure    3-1 
formatting 

display  screen    11-180 
screen  display     11-122  - 
11-127 
functions    7-7  -  7-10 
Boolean  type    7-10 
byte  type    7-9 
integer  type     7-9 
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functions  (cont'd) 
logical    7-10 

numeric  type    7-9,  10-7 
real  type    7-8 
string    7-10,  10-7 
trace    5-5  -  5-6 

transcendental     10-7 

GCOLR  (medium-res)    9-9 
GCSET  command  (high- 
res)    9-95 
GET  command    8-5,  11-58 
high-resolution    9-96 
GET/PUT  buffer    9-78 

high-resolution    9-101 
GET/PUT  commands  (high- 
res)    9-47 
global  symbol  (editor)    4-5 
GLOC  (medium-res)    9-9, 

9-20 
GOSUB/RETURN 

commands    11-61 
GPLOAD  command  (high- 
res)    9-98 
graphics 

characters    1-6 
cursor  (high-res)     9-95, 

9-119 
cursor  (medium-res) 

9-9,  9-27 
high-resolution    9-31  - 

9-126 
levels    9-1 

logic  functions    9-105 
low  resolution    9-4  -  9-8 
medium-resolution    9-8  - 

9-30 
memory  deallocate    9-30 
number  of  levels    1-2 
pattern  (high-res) 

9-111  -  9-112 
pointer  (high-res)     9-42 
screen  (medium-res) 
9-26 


graphics  (cont'd) 

screen  location  (medium- 
res)    9-20  -  9-21 
window    9-35  -  9-36 
with  128K    9-37  -  9-40 
greater  than    7-3,  7-5 
grid  format  (medium-res) 

9-10 
group 


buffer  (high-res) 

9-102 
number    9-78 


9-101  - 


hardware  window    9-32  -  9-35 
high-resolution    9-31  -  9-126 
adapter    9-22 
characters    9-8 
colors    9-109  -  9-110 
quick  reference    9-44  - 

9-49 
text    9-42 
hour    11-27 

I-Code    3-3,  12-1 

IF/THEN/ELSE  loop    11-35 

IF/THEN/ELSE/ENDIF 
commands    11-63  - 11-65 

image,  get  (high-res)    9-98 

immortal  shell     9-32 

initialize  a  disk  file     11-23  - 
11-24 

INIZ  command    9-32-9-33 

Inkey  program    B-l  -  B-2 

INPUT  command    8-5,  11-68  - 
11-70 

input/output    12-4 

insert 

a  line  (high-res)     9-99  - 

9-100 
text  (editor)    4-1 

INSLIN  command  (high- 
res)    9-99  -  9-100 

INT  command    11-71 

integer 

constants    6-7 


Index 


integer  (cont'd) 

data  type    6-1,  6-2,  6-3 
functions    7-9 
numeric  range    6-2 
interfacing  with  OS-9     1-1 
invisible  cursor  (high-res) 
9-71 

JOYSTK    9-9,9-22 

jump 

to  line  number    11-102  - 
11-103 

to  subroutine    11-100  - 
11-101 

key 

ALT    1-6,9-4 
BREAK    1-6, 5-2 
CLEAR    1-6 
CTRL     1-6  -  1-7 
ENTER    1-7 
key  sequence 

CTRL  with  other 
keys    1-6  - 1-7 
SHIFT  with  other 
keys    1-6 
keyword    11-1 
KILL  command    3-1,  3-6, 

10-9,  11-72  - 11-73 
KILLBUFF  command  (high- 
res)    9-101 
killing  a  procedure    3-6 

LAND  command    11-74  - 

11-75 
language  modules    1-5 
last  line,  displaying    1-7 
left  brace    1-6 
left  bracket    1-6 
LEFT$  command    11-76 
LEN  command     11-77 
length  of  string  variables    6-4 
less  than    7-3  -  7-4,  7-5 


LET  command    6-8,  11-78  - 
11-79 

debug    5-3 
LINE  (medium-res)    9-9 
line 

accessing  (editor)    4-5 
adding    4-10  -  4-12 
adding  (editor)    4-10 
erasing    9-90 

see  also  line,  deleting 
inserting  (high-res) 

9-99  -  9-100 
jumping  to     11-102  - 

11-103 
numbers    4-5 
renumbering    4-2,  4-10 
LINE  command 

high-resolution    9-103 
medium-resolution    9-24 
line  deleting    1-6,  2-2,  9-92 
editor    4-2 
high-resolution    9-80 
in  procedures    4-6  -  4-7 
LIST  command    3-1,  3-2  -  3-5, 

4-6, 10-9 
listing 

procedures    3-2  -  3-5, 

6-6,  10-9 
procedure  lines 
(editor)     4-2 
to  a  file    3-4 
to  a  printer    3-4 
LNOT  command    11-80  - 

11-81 
LOAD  command    3-1,  3-6, 

10-9 
loading 

a  buffer  (high-res)    9-98 
BASIC09    1-2-1-4 
procedures    3-1,  3-6, 

10-9 
window  image  (high- 
res)    9-101  -  9-102 
local  variable    6-7 
LOG  command    11-82 
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LOG10  command    11-83 
logarithm     11-82,  11-83 
logic  comparison    6-5 
LOGIC  command  (high- 
res)    9-105  -  9-106 
logical 

AND    11-8,  11-74  - 

11-75 
block  (file)    8-1 
complement    11-96 
functions    7-10 
NOT    11-80  -  11-81, 

11-96 
operators    7-7 
OR    11-87  -  11-88 
XOR    11-89  -  11-91 
loop 

EXITIF/ENDEXIT/ 
ENDEXIT    11-38, 
11-47  -  11-49 
FOR/NEXT    11-55, 
11-57,  11-95, 
11-159  - 11-160 
IF/THEN/ELSE/ENDIF 
11-35,  11-39, 
11-63  -  11-65 
LOOP/ENDLOOP 

11-40,  11-84-11-86 
REPEAT/UNTIL 
11-137  - 11-139, 
11-179 
WHILE/DO/ 

ENDWHILE     11-34, 
11-41,  11-183  -  11-184 
loop  repetition    11-95 
LOR  command    11-87  -  11-88 
low-resolution    9-1  -  9-7 
LXOR  command    11-89  - 
11-91 

math    1-2 

medium-resolution    9-8  -  9-30 

format    9-10-9-11 
MEM  command    1-3  - 1-4, 
3-1, 10-9 


memory 

changing    11-116- 

11-117 
examining     11-113  - 

11-114 
in  the  workspace    3-1 
requesting    1-3  -  1-4 
saving    1-2 
size     1-3,  1-4 
message,  end-of-file    1-6 
MID$  command    11-92 
minimizing  storage    12-1 
minutes     11-27 
mistakes  in  program  lines 

2-2 
mixing  data  types    7-2 
MOD  command    11-93 
MODE  (medium-res)    9-9, 

9-26 
modes 

command     1-3 
edit    1-4 
module 

execution     11-15 
high-resolution    9-31 
medium-resolution    9-8 
9-9 
modulus    11-93  11-94 
month     11-27 
mouse  (medium-res)    9-22 
MOVE  (medium-res)    9-9, 

9-27 
move  cursor    1-6 

high-resolution    9-68, 
9-70,  9-73  -  9-75 
move 

backward  (editor)    4-5 
draw  pointer  (high- 
res)    9-125 
graphics  cursor  (high- 
res)    9-95 
the  edit  pointer    4-1 
multipass  compiler    12-1 
multiplication    7-3  -  7-4 
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Index 


natural  exponent    11-50 
negation    7-3 
nesting  order  (debug)    5-3 
NEXT  command    11-95 
NOT  command     11-96 
not  equal  to    7-3,  7-4,  7-5 
NOT,  logical    11-80  - 11-81 

operator    7-4,  7-7 
null  constants    6-9 
numbers  for  lines    4-5 
numeric 

constants    6-6 

data  conversion    11-162  - 
11-163 

data  types    12-1  - 12-2 

functions     10-7 

type  conversion    11-54, 
11-71 

type  functions    7-9 

ON  ERROR/GOTO 

command    11-97  -  11-99 
ON/GOSUB  command 

11-100  -  11-101 
ON/GOTO  command     11-102  - 

11-103 
OPEN  command    8-3, 

11-104  - 11-105 
operands    7-2 
operators     7-1 

arithmetic    7-3  -  7-4 

equal    7-5 

greater  than    7-5 

hierarchy  of    7-4 

less  than     7-5 

logical    7-7 

relational    7-5  -  7-6 

string    7-6 

types    7-3 

unequal    7-5 
OR 

command     11-106 

logical     11-87  -  11-88 

operator     7-7 


order 

of  nesting  (debug)    5-3 
of  operators     7-4  -  7-5 
OS-9  commands    11-152 
accessing    3-7  -  3-8 
overlay  windows    9-41,  9-107  - 

9-108 
OWSET  command  (high- 
res)    9-107-9-108 

PACK  command    3-1,  3-8,  3-9, 
10-9, 12-4 

paint  (high-res)    9-93 
PALETTE  command  (high- 
res)    9-109-9-110 
palette 

default  colors    9-79 
high-resolution    9-34  - 

9-35 
registers    9-35 
PARAM  command    6-8, 

11-108  -  11-111 
passing  variables    6-8, 

11-108  -  11-111 
path 

input    11-68 
opening    11-104  -  11-105 
PATTERN  command  (high- 
res)    9-111-9-112 
PAUSE  command    5-5,  11-112 
PEEK  command    9-20, 

11-113  -  11-114 
PI  command    11-115 
pixel  9-34 

color  (medium-res) 

9-28  -  9-29 
set  (high-res)    9-113  - 
9-114 
plus  sign    7-6 
POINT 

high-resolution    9-113  - 

9-114 
medium-resolution    9-10, 
9-28  -  9-29 
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pointer 

draw  (hi-res)    9-42, 
9-125 

draw  (medium-res)    9-12 

edit    4-1 

file    8-5 

graphics    9-42 

READ    11-140 
POKE  command    9-20,  11-116 
POS  command    11-118 
position 

graphics  cursor  (medium- 
res)    9-9 

of  a  record  in  a  file    8-5 

of  cursor    11-118 
power  of  2    11-157 
predefined  windows    9-32  - 

9-33 
PRINT  command    11-119- 
11-120 

debug    5-3 
PRINT  USING  command 

11-122  - 11-128, 
11-180  -  11-182 
printer,  listing  files    3-4 
printing  (tabs)    11-166- 

11-167 
procedure 

changing    1-4 

comments    11-135  - 
11-136 

compilation    10-9 

compiling     1-5 

compressing    12-1 

condensing    3-1 

data  size    3-2 

deleting     3-6 

disassembling    3-3 

display    3-1 

displaying  information 
about    3-1 

erasing    3-1,  11-72  - 
11-73 

examining    4-4 

executing     1-5 


procedure  (confd) 

execution    2-3,  3-1 
grouping    1-4 
listing    3-2  -  3-3,  4-6 
loading    3-6 
renaming    3-2 
returning  from    11-141 
saving    3-1,  3-5  -  3-6, 

10-9 
size    3-2 

suspending    11-112 
terminating     11-36  - 

11-37,  11-161 
tracing    11-174 
writing    2-1  -  2-2 
procedures 

executable    3-8 
executing    11-145  - 

11-147 
loading    3-1 
program 

execution  termination 

1-6 
mistakes    2-2 
modular    1-1 
proportional  text  (high-res) 

9-115  -  9-116 
PROPSW  command  (high- 
res)    9-115  -  9-116 
protect  window  switch  (high- 
res)    9-85 
PUT  command    8-5,  8-6, 
9-117  -  9-118, 
11-129-11-130 
PUTGC  command    9-119 

QUIT  (medium-res)    9-10, 

9-30 
quit 

BASIC09    1-5, 3-1 

debug     5-3 

the  editor    2-3,  4-2 

RAD  command    5-2,  11-131 
radians    5-2,  11-131 
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random  access  files    8-5  -  8-11 
and  arrays    8-9-8-11 
creating    8-6  -  8-9 
random  value    11-143  - 

11-144 
range  of  numbers  6-2 
READ  8-4,  11-25,  11-132- 
11-133 

file  access    8-1 
read 

input    11-66-11-70 
pixel  color  (medium- 
res)    9-9 
read  a  record    11-58  -  11-60 
real 

constants     6-7 
data  type    6-1  -  6-4 
functions    7-8 
number  conversion 

11-71 
number  range    6-2 
number  rounding    11-53 
record    8-2 

binary  data     11-58 
position    8-5 
rectangle,  drawing  (high- 
res)    9-52-9-53,9-60- 
9-61 
reduce  memory  size     1-4 
registers  palette    9-35,  9-109  - 

9-110 
relational  operators    7-5  -  7-6 
relative  storage  area    3-3 
REM  command     11-135  - 

11-136 
remainder  (division)    11-93 
removing 

disk  files    11-30 
procedures    3-6,  10-9, 

11-72 
spaces    11-172-11-173 
RENAME  command    3-1 
renaming  procedures    3-2 
renumbering  lines  (editor) 
4-2,  4-10 


REPEAT/UNTIL 

commands    11-137  - 

11-139,  11-179 
requesting  memory    1-3  -  1-4 
reset  file  pointer     11-148  - 

11-149 
RESTORE  command    11-140 
retrieving  bytes  from  a  file 

8-5 
RETURN  command    11-141 
returning 

from  subroutine    11-61  - 

11-62 
to  OS-9    10-9 
reverse  video  (high-res)    9-120 
REVON  command  (high- 
res)    9-120 
rewind  a  file     8-11 
right  brace    1-6 
right  bracket    1-6 
RIGHT$  command    11-142 
ring  bell    9-54 
RND  command    11-143  - 

11-144 
ROOT  directory    3-7 
rounding  a  real  number 

11-53 
RUN  command    3-1,  6-8,  10-9, 

11-145  -  11-147 

SAVE  command    3-1,  3-5, 10-9 
saving 

a  window  area    9-96  - 

9-97 
graphic  images  (high- 
res)    9-117-9-118 
memory     1-2 
procedures    3-1,  3-5 
space  by  compiling    1-2 
SCALESW  command  (high- 
res)    9-121  -  9-122 
screen 

alphanumeric    9-30 
blink  (high-res)    9-55 
clearing  (high-res)    9-64 
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screen  (confd) 

clearing  (medium- 
res)    9-9,  9-17 
color  (medium-res)    9-26 
display     11-122 
format  (medium-res) 

9-26 
formatting    11-180 
location  (medium-res) 

9-20  -  9-21 
resolution    9-31 
selecting  (medium- 
res)    9-13-9-14 
switching  (medium- 
_  res)    9-9 
searching 

for  text  (editor)    4-2,  4-9 
in  strings    11-164  - 
11-165 
seconds     11-27 
SEEK  command    11-148  - 

11-149 
select  a  window    9-32  -  9-33 
SELECT  command  (high- 
res)    9-123  -  9-124 
selecting  memory    1-3 
sending  a  carriage  return 

9-67 
sentence-creating 
procedure    4-3 
sequential  file  writes 

11-185  -  11-186 
SETDPTR  command  (high- 
res)    9-125 
setting 

a  point  (medium-res) 

9-10,  9-28  -  9-29 
border  color  (high- 
res)    9-58  -  9-59 
color  (medium-res)    9-18 
pixel  (high-res)    9-113  - 

9-114 
READ  pointer     11-140 
screen  (medium-res)    9-9 
SGN  command    11-150  - 
11-151 


SHELL  command    11-152  - 

11-153 
shell  commands    10-9 
SHIFT--*-  key  sequence    1-6 
SHIFT-BREAK  key 

sequence    1-6 
SHIFT-CLEAR  key 

sequence    1-6 
show  text    11-119  - 11-121 
sign  of  a  value    11-150- 

11-151 
simulating  an  error    11-45  - 

11-46 
SIN  command    11-154 
sine    11-154 
single-dimensioned  array 

6-9  -  6-10 
SIZE  command    11-155  - 

11-156 
size 

data    3-2 
memory    1-3 
procedure    3-2 
space 

removing     11-172  - 

11-173 
saving  by  compiling    1-2 
spaces  in  command  lines    2-2 
special  keys    1-5  - 1-7 
speed 

of  arithmetic 

functions    12-2 
of  execution     1-1 
SQ  command     11-157 
SQR/SQRT  commands    11-158 
square  root     11-158 
starting 

a  shell  in  a  window    9-36 
BASIC09     1-2  -  1-4 
STATE  command  (debug)    5-3 
statements     10-7 
status  of  joystick  (medium- 
res)    9-22  -  9-23 
STEP  command    5-4, 11-159  - 
11-160 
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step  rate  (debug)    5-4 
stepping  through 

procedures    5-5  -  5-6 
STOP  command    11-161 

stop  program  execution    1-6 
storage 

area  of  command 

lines    3-3 
minimization     12-1 
of  variables     11-31  - 
11-33 
storing 

data    11-25  -  11-26 
in  memory     11-116  - 
11-117 
STR$  command    11-162  - 

11-163 
string 

constants    6-7 

data  conversion    11-181  - 

11-182 
data  type    6-1  -  6-2 
functions    10-7 
length    6-4,  11-77 
operators    7-6 
storage    6-5 
variables    6-4  -  6-5 
strings 

appending    7-6 
portioning    11-76,  11-92, 

11-142 
searching    11-164 
structured  programming     1-1 
structures,  complex  data 

8-11  -  8-15 
subroutine 

commands     11-61  -  11-62 
jumps    11-100  - 11-101 
SUBSTR  command    11-164  - 

11-165 
substrings    11-92 
subtraction    7-3  -  7-4 
suspending  execution    11-112 
switching  screens  (medium- 
res)    9-9,9-13-9-14 


symbolic  debugging    5-1 

syntax    11-1 

system 

commands    3-1 

interfacing    1-1 

TAB  command     11-166  - 

11-167 
TAN  command    11-168 
tangent    11-168 
terminating 

a  procedure    11-36  - 

11-37, 11-161 
the  editor    4-2 
test  for  end-of-file     11-42 
text 

changing    4-2,  4-7  -  4-9 
characters  (high-res) 

9-94 
display     11-119-11-121 
fonts     9-43  -  9-44 
formatting     11-122  - 

11-128 
high-resolution     9-42  - 

9-44 
proportional    9-115  - 

9-116 
searching    4-2,  4-9 
cursor  commands  (high- 
res)    9-48 
three-dimension  arrays    6-13 
tilde    1-6 

time     11-27  -  11-28 
tracing 

execution    5-4  -  5-6, 
11-174 
transcendental  functions     10-7 
trapping  errors    11-97  - 11-99 
TRIMS  command     11-172- 

11-173 
TROFF  command  (debug) 

5-4,  11-174 
TRON  command    5-4  -  5-6, 
11-174 
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TRUE  command    11-175  - 

11-176 
turning  off  the  cursor    9-71 
two-dimension  array    6-9 
type 

conversion     6-6,  7-2 

mismatch    6-6 

of  data    6-1-6-16,10-8 

of  file  access    8-1 

of  operators    7-3 
TYPE  command    8-12, 
11-177  -  11-178 

underscore    1-6 

UNDLNOFF  command  (high- 
res)    9-126 

UNDLNON  command  (high- 
res)    9-126 

unequal    7-5 

UNTIL    11-137  -  11-139, 
11-180 

up  arrow    1-6 

UPDATE     8-1,8-4 

USING  command    11-180- 
11-182 

using  debug    5-4  -  5-5 

V&L  command    11-181  - 
11-182 

value 

absolute     11-4 
Boolean    11-51-11-52 
random    11-143-11-144 

variable 

address    6-8,  11-6 
initialization    6-8 
local    6-7 
passing    6-8  -  6-9, 
11-108-11-111 
size    11-155  -  11-156 
storage    11-31  - 11-33 
value  of    11-78-11-79 

variables     1 1-2 

assigning  (debug)    5-3 


local    6-7 

string    6-4  -  6-5 
vector    6-13 
vertical  bar     1-6 
video 

address  (medium-res) 
9-9 

reverse  (high-res)    9-120 
visible  cursor  (high-res)    9-72 

WCREATE  command    9-33  - 

9-34 
WHILE/DO/ENDWHILE 
loop     11-34,  11-41, 
11-180  -  11-181 
whole  number,  range    6-2 
wildcard 

editor    4-1 
using  with  commands 
3-5 
window 

area,  saving    9-96  -  9-97 
commands  (high-res) 

9-45 
deallocating  (high- 
res)     9-83  -  9-84 
defining  (high-res) 

9-86  -  9-87 
display    1-6,  9-123  - 

9-124 
erasing    9-91 
establishing    9-32  -  9-41 
formats    9-34 
graphics    9-35-9-36 
hardware    9-32  -  9-35 
image  (high-res)    9-101  - 

9-102 
overlay  (high-res) 

9-107  -  9-108 
protect  switch  (high- 
res)    9-85 
shell    9-36 

working  area  (high-res) 
9-76  -  9-77 
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windows 

defining    9-33  -  9-34 
fromBASIC09    9-39- 

9-41 
overlay    9-41 
predefined    9-32-9-33 
with  high-resolution 
9-31 
working  area  (high-res)      9-76 
workspace     1-3, 3-1 
WRITE  command    11-185- 
11-186 


writing 

a  procedure    2-1  -  2-2 
to  files    8-3,  11-129 


XOR  command 

11-188 
XOR  operator 

year    11-27 


11-187- 
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Chapter  1 

Types  of  OS-9  Windows 


Unlike  many  operating  systems,  OS-9  has  a  built-in  windows 
program.  This  driver,  the  Windowing  System,  lets  you  lay  one  or 
more  smaller  screen  displays,  called  windows,  on  your  screen 
display. 

With  these  windows,  you  can  perform  several  tasks  at  the  same 
time,  For  example,  suppose  you  are  writing  a  business  letter 
using  a  word  processor  in  one  window,  Ifou  can  go  to  a  spread- 
sheet program  in  another  window,  get  a  price  quote  you  need, 
return  to  the  word  processor,  and  include  the  price  in  the  letter. 

The  Windowing  System  allows  as  many  windows  as  your  com- 
puter's memory  can  support,  with  a  maximum  of  32  at  one  time. 

In  OS-9,  there  are  two  types  of  windows:  device  and  overlay. 

Device  Windows 

A  device  window  is  one  that  can  run  a  program  or  utility.  This 
is  the  type  of  window  you  would  use  in  the  word  processor/ 
spreadsheet  example  given  above.  Each  device  window  acts  as  an 
individual  terminal. 

The  device  windows  are  designated  as  devices  /wl  -  /w7.  You 
open  a  device  window  as  you  do  any  other  OS-9  device.  You  tell 
OS-9  the  window's  parameters — including  whether  the  window  is 
for  text  or  graphics.  If  you  want  to  run  a  process  in  the  window, 
you  can  start  an  execution  environment,  such  as  a  shell,  on  the 
window.  (See  "Opening  a  Device  Window,"  later  in  this  chapter, 
and  the  DWSet  command  in  Chapter  3.) 

Note:  If  you  want  only  to  send  output  to  the  device  win- 
dow— without  running  a  process  in  the  window — do  not 
start  a  shell  on  the  window. 

Device  windows  cannot  overlay  each  other,  and  their  boundaries 
cannot  overlap. 
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Overlay  Windows 

An  overlay  window  is  a  window  that  you  open  on  top  of  a  device 
window.  (You  can  place  overlay  windows  over  other  overlay  win- 
dows, but  there  must  always  be  a  device  window  at  the  bottom  of 
the  stack.)  The  purpose  of  overlay  windows  is  to  display  com- 
puter dialog.  You  cannot  fork  a  shell  to  an  overlay  window;  how- 
ever, you  can  run  a  shell  in  an  overlay  window.  Overlay  windows 
assume  the  screen  type  of  the  device  windows  they  overlay. 

Opening  a  Device  Window 

To  open  a  device  window,  follow  these  steps: 

1.      If  you  want  to  allocate  memory  for  the  window,  use  OS-9's 
iniz  command.  Type; 

iniz    /w  number  I  ENTER  I 


where  number  is  the  number  of  the  device  window  you  wish 
to  open  (1-7).  If  you  do  not  specify  number,  OS-9  uses  the 
next  available  device  window  number. 

If  you  do  not  use  the  iniz  command,  memory  is  allocated 
dynamically  (as  needed)  to  the  window. 

2.      Next,  you  send  an  escape  sequence  to  OS-9  that  tells  it  the 

window's  parameters.  These  parameters  include  the  screen 
type,  size,  and  colors.  For  example: 

wcreate    -s=    2    20    10    40    10    01     00    0  0  |  ENTER  | 
or 

display    1b    20    02    14    0a   28    0a    01     00    0 0  |  ENTER  | 

sends  the  escape  sequence  for  the  next  available  window  to 
theDWSet  command.  The  wcreate  command  lets  you  use 
decimal  numbers,  while  the  display  command  requires 
hexadecimal  numbers. 


1-2 


3. 


Types  ofOS-9  Windows  1 1 


If  you  wish  to  send  an  escape  sequence  to  a  specific  win- 
dow, route  the  command  to  that  device.  For  example: 


wcreate    -s-    2    20    10    40    1 


10    >/w2 


ENTER 


sends  the  escape  sequence  to  device  /w2.  The  functions  of 
the  codes,  as  used  in  the  wcreate  command,  are  as  follows; 

2  sets  a  screen  type  of  80  x  24  (text  only), 

20  starts  the  window  at  character/column  20, 

10  starts  the  window  at  line/row  10. 

40  sets  a  window  size  of  40  characters. 

10  sets  a  window  size  of  10  lines. 

01  sets  the  foreground  color  to  blue, 

00  sets  the  background  color  to  white, 

00  sets  the  border  to  white. 

If  you  do  not  send  escape  sequences,  OS-9  uses  default 
descriptors  for  the  windows.  The  defaults  are: 


Size 

Window 

Screen  Type 

Starting  Position 

(columns, 

Number 

(chars./line) 

(horiz.,  vert.) 

rows) 

1 

40  (text) 

0,0 

27,11 

2 

40  (text) 

28,0 

12,11 

3 

40  (text) 

0,12 

40,12 

4 

80  (text) 

0,0 

60,11 

5 

80  (text) 

60,0 

19,11 

6 

80  (text) 

80,0 

80,12 

7 

80  (text) 

0,0 

80,24 

Use  OS-9's  shell  command  to  fork  a  shell  to  the  window. 
Type: 


shell    i  =  /wnumber    &  I  ENTER  ] 


where  number  is  the  number  used  in  the  iniz  or  wcreate 
command.  The  i=  parameter  creates  an  immortal  shell. 
Creating  an  immortal  shell  protects  the  window  and  its 
shell  from  being  destroyed  if  you  accidentally  exit  the  shell 
using  |  ctrl  ||  break] .  If  you  omit  the  i=  parameter,  the  shell 
is  forked  to  the  next  available  device  window. 

You  now  have  a  window  that  can  run  its  own  tasks.  Information 
displayed  in  that  window  is  automatically  scaled  to  the  window's 
size. 
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Opening  an  Overlay  Window 

To  open  an  overlay  window,  use  the  Overlay  Window  Set  func- 
tion. (See  OWSet  in  Chapter  3,  "General  Commands.") 
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Overview  of  Commands  and 
Parameters 


The  windowing  commands  are  divided  among  three  chapters, 
based  on  their  functions. 

Chapter  3  describes  the  general  commands.  These  commands  let 
you  create  windows  and  buffers,  access  buffers,  set  switches,  and 
maintain  the  window  environment. 

Chapter  4  describes  the  drawing  commands.  Besides  letting  you 
draw  all  kinds  of  images  (circles,  ellipses,  arcs,  and  boxes,  to 
name  a  few),  these  commands  also  enable  you  to  color  areas  or  to 
fill  them  with  patterns. 

Chapter  5  describes  the  text  commands.  Use  these  commands  to 
manipulate  the  text  cursor  and  the  text  attributes.  Text  com- 
mands operate  on  hardware  text  screens  (Screen  Types  1  and  2) 
and  graphics  windows  if  a  font  is  selected. 

Each  command  description  lists  the  command's  name,  code,  and 
parameters.  To  call  a  Windowing  System  command  using  OS-9's 
display  command,  type  display,  followed  by  the  command  code 
and  the  values  you  want  to  supply  for  the  parameters. 

Parameters 

The  following  is  a  complete  list  of  the  parameter  abbreviations 
used  in  Chapters  3,  4,  and  5.  All  parameters  represent  a  single 
byte  of  information. 

Parameter  Description 

HBX  high  order  byte  ofx  value 

LBX  low  order  byte  ofx  value 

HBY  high  order  byte  ofy  value 

LBX  low  order  byte  ofy  value 

HBXo  high  order  byte  ofx-offset  value  (relative) 

LBXo  low  order  byte  ofx-offset  value  (relative) 

HBYo  high  order  byte  of  y  -offset  value  (relative) 

LBYo  low  order  byte  of  y  -offset  value  (relative) 

HBR  high  order  byte  of  radius 

LBR  low  order  byte  of  radius 
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Parameter 


Description 


HBL 

LBL 

HSX 
LSX 
HSY 
LSY 

HBRx 

LBRx 

GRP 

BFN 

LCD 

PRN 

CTN 

FNM 

CPX 

CPY 

STY 

SVS 

SZX 
SZY 
XDR 

YDR 

BSW 


high  order  byte  of  length 
low  order  byte  of  length 

high  order  byte  of  size  in  x  direction 
low  order  byte  of  size  in  x  direction 
high  order  byte  of  size  in  y  direction 
low  order  byte  of  size  in  y  direction 

high  order  byte  of  radius  in  x  direction 
low  order  byte  of  radius  in  x  direction 

GET/PUT  buffer  group  number  (1-254) 

GET/PUT  buffer  number  (1-255) 

logic  code  number 

palette  register  number  (0-15,  wraps  mod  15) 

color  table  number  (0-63,  wraps  mod  64) 

font  number 

character  position  x  (0-xmax) 

character  position  y  (O-vmax) 

screen  type 

save  switch  (0  =  nosave,  1  =  save  area  under 

overlay) 

size  in  x  (columns) 

size  in  y  (rows) 

dimension   ratio  x   used   with   YDR   as   YDRi 

XDR 

dimension  ratio  y 

binary  switch  (0  =  off,  l  =  on) 
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The  general  commands  let  you  set  up  and  customize  windows. 
They  also  let  you  set  up  and  access  image  buffers  and  select 
colors  for  the  screen. 
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B Color  Background  Color 


Function:  Lets  you  choose  a  color  palette  register  to  use  as  the 
background  color.  See  the  Palette  command  for  setting  up  the 
actual  colors. 

Code:  IB  33 

Parameters:  PRN 
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BoldSw  Bold  Switch 


Function:  Enables  or  disables  boldfacing  for  text  on  graphics 
screens.  If  boldface  is  on,  the  screen  displays  subsequent  char- 
acters in  bold.  If  boldface  is  off,  the  screen  displays  subsequent 
characters  in  the  regular  font. 

Code:  IB  3D 

Parameters:  BSW 

BSW  =  switch 

00  =  off  (Default) 

01  =  on 

Notes: 

•  You  can  use  BoldSw  with  any  font. 

•  Boldface  is  not  supported  on  hardware  text  screens  (Screen 
Types  1  and  2). 
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Border  Border  Color 


Function:  Lets  you  change  the  palette  register  used  for  the 
screen  border.  See  the  Palette  command  for  setting  up  the 
actual  colors. 

Code:  IB  34 

Parameters:  PRN 

Notes: 

•  You  set  the  border  by  selecting  a  palette  register  to  use  for 
the  border  register.  When  the  actual  color  is  changed  in  the 
palette  register  selected  by  the  command,  the  color  of  the 
screen  border  changes  to  the  new  color.  In  general,  the  bor- 
der register  usually  matches  the  background  palette 
register. 
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C\M\rea  Change  Working  Area 


Function:  Lets  you  alter  the  working  area  of  the  window.  Nor- 
mally, the  system  uses  this  call  for  high-level  windowing,  but 
you  can  use  it  to  restrict  output  to  a  smaller  area  of  the  win- 
dow. 

Code:  IB  25 

Parameters:  CPX  CPY  SZX  SZY 

Notes: 

•  You  cannot  change  a  window's  working  area  to  be  larger 
than  the  predefined-  area  of  the  window  as  set  by  DWSet  or 
OWSet. 

•  All  drawing  and  window  updating  commands  are  done  on 
the  current  working  area  of  a  window.  The  working  area 
defaults  to  the  entire  size  of  the  window.  Scaling,  when  in 
use,  is  also  performed  relative  to  the  current  working  area 
of  a  window.  The  CWkrea  command  allows  users  to  restrict 
the  working  area  of  a  window  to  smaller  than  the  full  win- 
dow size.  Functions  which  might  be  done  by  opening  a  non- 
saved  overlay  window  to  draw  or  clear  an  image  and  then 
closing  the  overlay  can  be  accomplished  by  using  this  com- 
mand to  shorten  execution  time  where  an  actual  overlay 
window  is  not  needed. 
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DefColr  Default  Color 


Function:  Sets  the  palette  registers  back  to  their  default  val- 
ues. The  actual  values  of  the  palette  registers  depend  on  the 
type  of  monitor  you  are  using.  (See  montype  in  OS  -9  Level 
Two  Commands.) 


Code: 


IB  30 


Parameters:  None 


Notes: 


The  default  color  definitions  apply  only  to  high-resolution 
graphics  and  text  displays. 

The  system  sets  the  palette  registers  to  a  proper  compati- 
bility mode  when  switching  to  screens  using  the  older  VDG 
emulation  modes.  See  the  table  below: 


Window  System 
Color  Modes 

VDG-Corapatible  Modes 

Palette 

Color 

P#  Color 

P#  Color 

00&08 

White 

00  Green 

08  Black 

01&09 

Blue 

01  Yellow 

09  Green 

02  &  10 

Black 

02  Blue 

0A  Black 

03  &  11 

Green 

03  Red 

0B  Buff 

04  &  12 

Red 

04  Buff 

0C  Black 

05  &  13 

Yellow 

05  Cyan 

0D  Green 

06  &  14 

Magenta 

06  Magenta 

0E  Black 

07&15 

Cyan 

07  Orange 

OF  Orange 

The  SetStat  call  lets  you  change  the  default  color  palette 
definition  when  using  the  windowing  system.  Default  colors 
in  the  VDG-Compatible  Mode  cannot  be  changed.  See  the 
OS -9  Level  Two  Technical  Reference  manual  for  information 
on  SetStat. 

The  system's  default  colors  are  used  whenever  you  create  a 
new  window. 
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DfnGPBuf  Define  GET/PUT  Buffer 


Function:  Lets  you  define  the  size  of  the  GET/PUT  buffers  for 
the  system.  Once  you  allocate  a  GET/PUT  buffer,  it  remains 
allocated  until  you  use  the  KilBuf  command  to  delete  it. 

OS-9  allocates  memory  for  GET/PUT  buffers  in  8K  blocks  that 
are  then  divided  into  the  different  GET/PUT  buffers.  Buffers 
are  divided  into  buffer  groups.  Therefore,  all  commands  deal- 
ing with  GET/PUT  buffers  must  specify  both  a  group  number 
and  a  buffer  number  within  that  group, 

Code:  IB  29 

Parameters:  GRP  BFN  HBL  LBL 

Technical: 

The  buffer  usage  map  is  as  follows: 

Group           Buffer 
Number       Number1    Use 

0  1  -  255      Internal  use  only  (returns  errors) 
1  -  199  1  -  255      General  use  by  applications2 

200  -  254         1  -  255      Reserved  (Microware  use  only)3 
255 \-255     Internal  use  only  (returns  errors) 

1  Buffer  Number  0  is  invalid  and  cannot  be  used. 

2  The  application  program  should  request  its  user  ID  via 
the  GetID  system  call  to  use  as  its  group  number  for 
buffer  allocation. 

3  The  standard  group  numbers  are  defined  as  follows: 

Note:  The  names,  buffer  groups,  and  buffer  numbers  are 
defined  in  the  assembly  definition  file.  The  decimal  num- 
ber you  use  to  call  these  are  in  parentheses  next  to  the 
name.  For  example,  to  select  the  Arrow  pointer, 
Grp  Jtr  and  Ptr_A.rr,  you  use  202,1  as  the  group/buffer 
number. 
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Grp_J Fnt(200)  =  font  group  for  system  fonts 

Fnt_S8x8(l)  =  standard  8x8  font 
FnLS6x8(2)  =  standard  6x8  font 
Fnt_G8x8(3)  =  standard  graphics  font 

The  standard  fonts  are  in  the  file  SYS/ 
StdFonts. 

Grp_Clip(201)  =  clipboarding  group  (for  Multiview) 

Grp_Ptr(202)  =    graphics  cursor  (pointer)  group 

Ptr_Arr ( 1 )  =  arrow  pointer  (hp = 0 ,0) 
Ptr_Pen(2)  =  pencil  pointer  (hp  =  0,0) 
Ptr_LCH(3)    =  large  cross  hair  pointer 

(hp  =  7,7) 
Ptr_Slp(4)       =  sleep  indicator  (hourglass) 
Ptr_Ill(5)        =  illegal  indicator 
Ptr_Txt(6)      =  text  pointer  (hp  =  3,3) 
Ptr_SCH(7)     =  small  cross  hair  pointer 

(hp  =  3,3) 

hp  =  hit  point,  the  coordinates 

of  the  actual  point  on  the 
object  at  which  the  cursor 
should  be  centered. 

The  standard  pointers  are  in  the  file  SYS/ 
StdPtrs. 

Grp_Pat2(203)  =  two  color  patterns 

Grp_Pat4(204)  =  four  color  patterns 

Grp_Pat6(205)  =  sixteen  color  patterns 

PaL_Dot(l)      =  dot  pattern 
Pat_Vrt(2)      =  vertical  line  pattern 
Pat _Hrz(3)      =  horizontal  line  pattern 
PaL_XHtc(4)   =  cross  hatch  pattern 
Pat_LSnt(5)    =  left  slanted  lines 
Pat_RSnt(6)    =  right  slanted  lines 
Pat_^SDot(7)    =  small  dot  pattern 
Pat_BDot(8)    =  large  dot  pattern 

Each  pattern  is  found  within  each  of  the 
pattern  groups. 

Standard  patterns  are  in  the  files 
SYS/StdPats_2,  SYS/StdPats_4,  and 
SYS/StdPats_16. 
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All  files  have  GPLoad  commands  imbedded  in  file,  along  with 
the  data.  To  load  fonts,  pointers,  or  patterns,  simply  merge  them 
to  any  window  device:  For  example; 


merge    SYS/St  dFont  5  [ENTERj 

sends  the  standard  font  to  standard  output  which  may  be  redi- 
rected to  another  device  if  the  current  output  device  is  not  a  win- 
dow device  (such  as  when  term  is  a  VDG  screen). 

You  only  need  to  load  fonts  once  for  the  entire  system.  Once  a 
Get/Put  buffer  is  loaded,  it  is  available  to  all  devices  and  pro- 
cesses in  the  system. 
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DWEnd  Device  Window  End 

Function:  Ends  a  current  device  window.  DWEnd  closes  the 
display  window.  If  the  window  was  the  last  device  window  on 
the  screen,  DWEnd  also  deallocates  the  memory  used  by  the 
window.  If  the  window  is  an  interactive  window,  OS-9  auto- 
matically switches  you  to  a  new  device  window,  if  one  is 
available. 

Code:  IB  24 

Parameters:  None 

Notes: 

•  DWEnd  is  only  needed  for  windows  that  have  been  attached 
via  the  iniz  utility  or  the  I$Attach  system  call.  Non- 
attached  windows  have  an  implied  DWEnd  command  that  is 
executed  when  you  close  the  path. 
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DWPrOtSw  Device  Window  Protect  Switch 


Function:  Disables  and  enables  device  window  protection.  By 
default,  device  windows  are  protected  so  that  you  cannot  over- 
lay them  with  other  device  windows.  This  type  of  protection 
helps  avoid  the  possibility  of  destroying  the  contents  of  either 
or  both  windows. 

Code:  IB  36 

Parameters:  BSW 

BSW  =  switch 

00  =  off 

01  =  on  (Default) 


Notes: 


We  recommend  that  you  not  turn  off  device  window  protec- 
tion. If  you  do,  however,  use  extreme  discretion  because  you 
might  destroy  the  contents  of  the  windows.  OS-9  does  not 
return  an  error  if  you  request  that  a  new  window  be  placed 
over  an  area  of  the  screen  which  is  already  in  use  by  an 
unprotected  window. 
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DWSet  Device  Window  Set 

Function:  Lets  you  define  a  window's  size  and  location  on  the 
physical  screen.  Use  DWSet  after  opening  a  path  to  a  device 
window. 

Code:  IB  20 

Parameters:  STY  CPX  CPY  SZX  SZY  PRN1  PRN2  PRN3 

PRN1  =  Foreground 
PRN2  =  Background 
PR.N3  =  Border  (if  STY  >  1) 


Notes: 


The  iniz  and  display  commands  open  paths  to  the  device 
window. 

When  using  DWSet  in  a  program,  you  must  first  open  the 
device. 

Output  to  a  new  window  is  ignored  until  OS-9  receives  a 
DWSet  command,  unless  defaults  are  present  in  the  device 
descriptor  (/wl-/w7).  If  defaults  are  present  in  the  device 
descriptors,  OS-9  automatically  executes  DWSet,  using 
those  defaults. 

When  OS-9  receives  the  DWSet,  it  allocates  memory  for  the 
window,  and  clears  the  window  to  the  current  background 
color.  If  the  standard  font  is  already  in  memory,  OS-9 
assigns  it  as  the  default  font.  If  the  standard  font  is  not  in 
memory,  you  must  execute  a  font  set  (Font)  command  after 
loading  the  fonts  to  produce  text  output  on  a  graphics 
window. 

Use  the  Screen  Type  code  (STY)  to  define  the  resolution 
and  color  mode  of  the  new  screen.  If  the  screen  type  code  is 
zero,  OS-9  opens  the  window  on  the  process's  currently 
selected  screen.  If  the  code  is  01,  OS-9  opens  the  window  on 
the  currently  displayed  screen.  If  the  code  is  non-zero,  OS-9 
allocates  a  new  screen  for  the  window.  The  following 
describes  the  acceptable  screen  types: 
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Code 

Screen  Size 

Colors 

Memory 

Type 

FF 

Current  Displayed  Screen1 

00 

Process's  Current  Screen 

01 

40x24 

8&8 

2000 

Text 

02 

80x24 

8&8 

4000 

Text 

05 

640  x  192 

2 

16000 

Graphics 

06 

320  x  192 

4 

16000 

Graphics 

07 

640  x  192 

4 

32000 

Graphics 

08 

320  x  192 

16 

32000 

Graphics 

1  Use  the  Current  Displayed  Screen  option  only  in  proce- 
dure files  to  display  several  windows  on  the  same  physical 
screen.  All  programs  should  operate  on  that  process's  cur- 
rent screen. 

•  The  location  of  the  window  on  the  physical  screen  is  deter- 
mined by  the  diagonal  line  defined  by: 

(CPX,CFY)  and  (CPX  +  SZX,  CPY  +  SZY) 

•  The  foreground,  background,  and  border  register  numbers 
(PRN1,  PRN2,  and  PRN3)  define  the  palette  registers  used 
for  the  foreground  and  background  colors.  See  the  Palette 
command  in  this  chapter  for  more  information. 

•  When  an  implicit  or  explicit  DWSet  command  is  done  on  a 
window,  the  window  automatically  clears  to  the  background 
color. 

•  All  windows  on  the  screen  must  be  of  the  same  type  (either 
text  or  graphics). 

•  Values  in  the  palette  register  affect  all  windows  on  the 
screen.  However,  you  can  choose  which  register  to  use  for 
foreground  and  background  for  each  window.  That  is,  OS-9 
maintains  palette  registers  and  border  register  numbers  for 
the  entire  screen  and  foreground  and  background  registers 
numbers  for  each  individual  window. 

•  OS-9  deallocates  memory  for  a  screen  when  you  terminate 
the  last  window  on  that  screen. 
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FColor  Foreground  Color 

Function:  Lets  you  select  a  color  palette  register  for  the  fore- 
ground color.  See  the  Palette  command  for  setting  the  actual 
colors. 

Code:  IB  32 

Parameters:  PRN 
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Font 


Select  Font 


Function:  Lets  you  select/change  the  current  font.  Before  you 
can  use  this  command,  the  font  must  be  loaded  into  the  speci- 
fied GET/PUT  group  and  buffer  (using  GPLoad).  See  the 
GPLoad  command  for  information  on  loading  font  buffers. 

Code:  IB  3A 

Parameters:  GRPBFN 


Notes: 


You  can  select  proportional  spacing  for  the  font  by  using 
PropSw. 

All  font  data  is  a  2-color  bit  map  of  the  font. 

Each  character  in  the  font  data  consists  of  8  bytes  of  data. 
The  first  byte  defines  the  top  scan  line,  the  second  byte 
defines  the  second  scan  line,  and  so  on.  The  high-order  bit 
of  each  byte  defines  the  first  pixel  of  the  scan  line,  the  next 
bit  defines  the  next  pixel,  and  so  on.  For  example,  the  letter 
"A"  would  be  represented  like  this: 


Byte 

3ixel  Representation 

10 

..#.... 

28 

.    #  .    #  . 

a 

44 

#.    .    .    # 

a 

44 

#  .    .    .    # 

» 

7c 

#  #  #  #  # 

v 

44 

#.    .    .    # 

* 

44 

#.    .    .    # 

a 

00 

Note  that  6x8  fonts  ignore  the  last  2  bits  per  byte. 

The  fonts  are  ordered  with  characters  in  the  following 
ranges: 

$00-$  IF        International  characters  (see  mapping  below) 
$20-$7F        Standard  ASCII  characters 
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International  characters  or  any  characters  in  the  font  below 
character  $20  (hex)  are  printed  according  to  the  following 
table: 


Character  position 

Charl           or 

CharS 

in  font 

$00 

c 

$C1  A 

$E1 

$01 

ii 

$C2  B 

$E2 

$02 

e 

$C3  C 

$E3 

$03 

a 

$C4  D 

$E4 

$04 

a 

$C5  E 

$E5 

$05 

a 

$C6   F 

$E6 

$06 

a 

$C7  6 

$E7 

$07 

s 

$C8  H 

$E8 

$08 

e 

$C9   I 

$E9 

$09 

e 

$ca  a 

$EA 

$0A 

e 

$CB  K 

$EB 

$0B 

i 

$CC  L 

$EC 

$0C 

f 

$CD  M 

$ED 

$0D 

13 

$CE  N 

$EE 

$0E 

A 

$CF  0 

$EF 

$0F 

0 

$D0  P 

$F0 

$10 

$D1  Q 

$F1 

$11 

se 

$D2  R 

$F2 

$12 

JE 

$D3  S 

$F3 

$13 

6 

$D4  T 

$F4 

$14 

6 

$D5  u 

$F5 

$15 

0 

$D6  V 

$F6 

$16 

u 

$D7  *J 

$F7 

$17 

u 

$D8  0 

$F8 

$18 

0 

$D9  ; 

$DA  z 

$F9 

$19 

O 

$FA 

$1A 

O 

$AA 

$BA 

$1B 

§ 

$AB 

$BB 

$1C 

£ 

$AC 

$BC 

$1D 

+ 

$AD 

$BD 

$1E 

0 

$AE 

$BE 

$1F 

f 

$AF 

$BF 
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(jr(_>06t  Graphics  Cursor  Set 

Function:  Creates  a  GET/PUT  buffer  for  defining  the  graphics 
cursor  that  the  system  displays.  You  must  use  GCSet  to  dis- 
play a  graphic  cursor. 

Code:  IB  39 

Parameters:  GRP  BFN 

Notes: 

•  Tb  turn  off  the  graphics  cursor,  specify  GRP  as  00. 

•  A  system  standard  buffer  or  a  user-defined  buffer  can  be 
used  for  the  graphics  cursor. 
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GetBlk  Get  Block 

Function:  Saves  an  area  of  the  screen  to  a  GET/PUT  buffer. 
Once  the  block  is  saved,  you  can  put  it  back  in  its  original 
location  or  in  another  on  the  screen,  using  the  PutBlk 
command. 

Code:  IB  2C 

Parameters:  GRP  BFN  HBX  LBX  HBY  LBY  HSX'LSX  HSY 
LSY 

HBX/LBX  =  x-Iocation  of  block  (upper  left  corner) 
HBY/LBX  =  y -location  ofbhck 
HSX/LSX  =  x-dimension  of  block 
HSY/LSY  =  y-dimension  of  block 


Notes: 


The  GET/PUT  buffer  maintains  information  on  the  size  of 
the  block  stored  in  the  buffer  so  that  the  PutBlk  command 
works  more  automatically. 

If  the  GET/PUT  buffer  is  not  already  defined,  GetBlk  cre- 
ates it.  If  the  buffer  is  defined,  the  data  must  be  equal  to  or 
smaller  than  the  original  size  of  the  buffer. 
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GPLoad  GET/PUT  Buffer  Load 


Function:  Preloads  GET/PUT  buffers  with  images  that  you 
can  move  to  the  screen  later,  using  PutBlk. 

If  the  GET/PUT  buffer  is  not  already  created,  GPLoad  creates 
it. 

If  the  buffer  was  previously  created,  the  size  of  the  passed 
data  must  be  equal  to  or  smaller  than  the  original  size  of  the 
buffer.  Otherwise,  GPLoad  truncates  the  data  to  the  size  of 
the  buffer. 

Code:  IB  2B 

Parameters:  GRP  BFN  STY  HSX  LSX  HSY  LSY  HBL  LBL 
(Data...) 

STY  =  format 

HSX/LSX  =  x-dimension  of  stored  block 
HSY/LSY  =  y -dimension  of  stored  block 
HBL/LBL  =  number  of  bytes  in  data 

Notes: 

•  Buffers  are  maintained  in  a  linked  list  system. 

•  Buffers  to  be  used  most  should  be  allocated  last  to  mini- 
mize the  search  time  in  finding  the  buffers. 

•  When  loading  a  Font  GET/PUT  Buffer,  the  parameters  are 
as  follows: 

GRP  BFN  STY  HSX  LSX  HSY  LSY  HBL  LBL 
(Data...) 

GRP  =  254 

STY  =  5 

HSX/LSX  =  x-dimension  size  of  Font  6  or  8 
HSY/LSY  =  y -dimension  size  of  Font  8 
HBL/LBL  =  size  of  font  data  (not  including  this 
header  information) 

See  the  Font  command  for  more  information  on  font  data. 


3-19 


OS-9  Windowing  System 


KUBuf  Kill  GET/PUT  Buffer 

Function:  Deallocates  the  buffer  specified  by  the  group  and 
buffer  number.  To  deallocate  the  entire  group  of  buffers,  set 
the  buffer  number  to  0. 

Code:  IB  2A 

Parameters:  GRP  BFN 

Notes: 

•  KilBuf  returns  memory  used  by  the  buffer  to  a  free  list. 
When  an  entire  block  of  memory  has  been  put  on  the  free 
list,  the  block  is  returned  to  the  system. 
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LSet  Logic  Set 


Function:  Lets  you  create  special  effects  by  specifying  the 
type  of  logic  used  when  storing  data,  which  represents  an 
image,  to  memory.  The  specified  logic  code  is  used  by  all  draw 
commands  until  you  either  choose  a  new  logic  or  turn  off  the 
logic  operation.  To  turn  off  the  logic  function,  set  the  logic  code 
to  00. 

Code:  IB  2F 

Parameters:  LCN 

LCN  =  logic  code  number 

00  =  No  logic  code;  store  new  data  on 

screen 

01  =  AND  new  data  with  data  on 
screen 

02  =  OR  new  data  with  data  on  screen 

03  =  XOR  new  data  with  data  on  screen 

Notes: 

•  The  following  tables  summarize  logic  operations  in  bit 
manipulations: 


AND 


OR 


First 
Operand 

1 
1 
0 
0 

First 
Operand 

1 
1 

0 
0 


Second 
Operand 

1 
0 
1 
0 

Second 
Operand 

1 
0 
1 

0 


Result 


1 
0 
0 
0 

Result 


1 
1 
1 
0 
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XOR  First  Second  Result 

Operand        Operand 

1  1  0 

10  1 

Oil 

0  0  0 

Data  items  are  represented  as  palette  register  numbers  in 
memory.  Since  logic  is  performed  on  the  palette  register 
number  and  not  the  colors  in  the  registers,  you  should 
choose  colors  for  palette  registers  carefully  so  that  you 
obtain  the  desired  results.  'You  may  want  to  choose  the 
colors  for  the  palette  registers  so  that  LSet  appears  to  and, 
or,  and  xor  the  colors  rather  than  the  register  numbers.  For 
example: 

Palette  #    Color  Alternative  Order 

0  White  Black 

1  Blue  Blue 

2  Black  Green 

3  Green  White 
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OWEnd  Overlay  Window  End 


Function:  Ends  a  current  overlay  window.  OWEnd  closes  the 
overlay  window  and  deallocates  memory  used  by  the  window. 
If  you  opened  the  window  with  a  save  switch  value  of  hexadec- 
imal 01,  OS-9  restores  the  area  under  the  window.  If  you  did 
not,  OS-9  does  not  restore  the  area  and  any  further  output  is 
sent  to  the  next  lower  overlay  window  or  to  the  device  window, 
if  no  overlay  window  exists. 

Code:  IB  23 

Parameters:  None 


3-23 


OS-9  Windowing  System 


OWSet  Overlay  Window  Set 

Function:  Use  OWSet  to  create  an  overlay  window  on  an  exist- 
ing device  window.  OS-9  reconfigures  current  device  window 
paths  to  use  a  new  area  of  the  screen  as  the  current  logical 
device  window. 

Code:  IB  22 

Parameters:  SVS  CPX  CPY  SZX  SZY  PRN1  PRN2 

SVS  =  save  switch 

00  =  Do  not  save  area  overlayed 

01  =  Save  area  overlayed  and  restore  at 

close 
PRN1  =  background  palette  register 
PRN2  =  foreground  palette  register 


Notes: 


If  you  set  SVS  to  zero,  any  writes  to  the  new  overlay  win- 
dow destroy  the  area  under  the  window.  You  might  want  to 
set  SVS  to  zero  if  your  system  is  already  using  most  of  its 
available  memory.  You  might  also  set  SVS  to  zero  whenever 
it  takes  relatively  little  time  to  redraw  the  area  under  the 
overlay  window  once  it  is  closed. 

If  you  have  ample  memory,  specify  SVS  as  1.  Doing  this 
causes  the  system  to  save  the  area  under  the  new  overlay 
window.  The  system  restores  the  area  when  you  terminate, 
the  new  overlay  window.  (See  OWEnd.) 

The  size  of  the  overlay  window  is  specified  in  standard 
characters.  Use  the  same  resolution  (number  of  characters) 
as  the  device  window  that  will  reside  beneath  the  overlay 
window.  Have  your  program  determine  the  original  size  of 
the  device  window  at  startup  (using  the  SS.ScSiz  GETSTAT 
call),  if  the  device  window  does  not  cover  the  entire  screen. 
See  the  OS-9  Level  Two  Technical  Reference  manual  for 
information  on  the  SS.ScSiz  GETSTAT  call. 
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Overlay  windows  can  be  created  on  top  of  other  overlay 
windows;  however,  you  can  only  write  to  the  top  most  win- 
dow. Overlay  windows  are  "stacked"  on  top  of  each  other 
logically.  To  get  back  down  to  a  given  overlay,  you  must 
close  (OWEnd)  any  overlay  windows  that  reside  on  top  of 
the  desired  overlay  window. 

Stacked  overlay  windows  do  not  need  to  reside  directly  on 
top  of  underlying  overlay  windows.  However,  all  overlay 
windows  must  reside  within  the  boundaries  of  the  underly- 
ing device  window. 
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Palette  Change  Palette 

Function:  Lets  you  change  the  color  associated  with  each  of 
the  16  palette  registers. 

Code:  IB  31 

Parameters:  PRN  CTN 

Notes: 

•  Changing  a  palette  register  value  causes  all  areas  of  the 
screen  using  that  palette  register  to  change  to  the  new 
color.  In  addition,  if  the  border  is  set  to  that  palette  regis- 
ter, the  border  color  also  changes.  See  the  Border  command 
for  more  information. 

Colors  are  made  up  by  setting  the  red,  green,  and  blue  bits 
in  the  color  byte  which  is  inserted  in  the  palette  register. 
The  bits  are  laid  out  as  follows: 


• 


Bit 

Color 

0 

Blue  low 

1 

Green  low 

2 

Red  low 

3 

Blue  high 

4 

Green  high 

5 

Red  high 

6 

unused 

7 

unused 

By  using  six  bits  for  color  (2  each  for  red,  green  and  blue) 
there  is  a  possibility  of  64  from  which  to  choose.  Some  of 
the  colors  are  defined  as  shown: 


White 
Black 
Standard  Blue 

Standard  Green 
Standard  Red 


00111111  =  $3F  (all  color  bits  set) 
00000000  =  $00  (no  color  bits  set) 
00001001  =  $09  (both  blue  bits  set) 
00010010  =  $12  (both  green  bits  set) 
00100100  =  $24  (both  red  bits  set) 
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Note:  These  colors  are  for  RGB  monitors.  The  composite 
monitors  use  a  different  color  coding  and  do  not  directly 
match  pure  RGB  colors.  To  get  composite  color  from  the 
RGB  colors,  the  system  uses  conversion  tables.  The  colors 
were  assigned  to  match  the  RGB  colors  as  close  as  possible. 
There  are,  however,  a  wider  range  of  composite  colors,  so 
the  colors  without  direct  matches  were  assigned  to  the  clos- 
est possible  match.  The  white,  black,  standard  green,  and 
standard  orange  are  the  same  in  both  RGB  and  composite. 


3-27 


OS-9  Windowing  System 


PrOpSw  Proportional  Switch 

Function:  Enables  and  disables  the  automatic  proportional 
spacing  of  characters.  Normally,  characters  are  not  proportion- 
ally spaced. 

Code:  IB  3F 

Parameters:  BSW 

BSW  =  switch 

00  =  off  (Default) 

01  =  on 


Notes: 


Any  standard  software  font  used  in  a  graphics  screen  can 
be  proportionally  spaced. 

Proportional  spacing  is  not  supported  on  hardware  text 
screens. 
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PSet  Pattern  Set 


Function:  Selects  a  preloaded  GET/PUT  buffer  as  a  pattern 
RAM  array.  This  pattern  is  used  with  all  draw  commands 
until  you  either  change  the  pattern  or  turn  it  off  by  passing  a 
parameter  of  00  as  GRP  (Group  Number). 

Code:  IB  2E 

Parameters:  GRP  BFN 

Notes: 

•  The  pattern  array  is  a  32  x  8  pixel  representation  of  graph- 
ics memory.  The  color  mode  defines  the  number  of  bits  per 
pixel  and  pixels  per  byte.  So,  be  sure  to  take  the  current 
color  mode  into  consideration  when  creating  a  pattern 
array. 

•  The  GET/PUT  buffer  can  be  of  any  size,  but  only  the  num- 
ber of  bytes  as  described  by  the  following  table  are  used: 

Color 

Mode Size  of  Pattern  Array 

2  4  bytes  x  8  =     32  bytes  (1  bit  per  pixel) 

4  8  bytes  x  8   =     64  bytes  (2  bits  per 

pixel) 
16  16  bytes  x  8   =    128  bytes  (4  bits  per 

pixel) 

•  The  buffer  must  contain  at  least  the  number  of  bytes 
required  by  the  current  color  mode.  If  the  buffer  is  larger 
than  required,  the  extra  bytes  are  ignored. 

•  To  turn  off  patterning,  set  GRP  to  00. 
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The  following  example  creates  a  two  color  pattern  of  vertical 
lines.  A  two  color  pattern  is  made  up  of  l's  and  O's.  The 
diagram  below  shows  the  bit  set  pattern  (note  that  one 
pixel  is  equal  to  one  bit): 

10101010101010101010101010101010 
10101010101010101010101010101010 
10101010101010101010101010101010 
10101010101010101010101010101010 
10101010101010101010101010101010 
10101010101010101010101010101010 
10101010101010101010101010101010 
10101010101010101010101010101010 

When  the  binary  for  the  2x8  pixel  data  is  compressed  into 
byte  data,  notice  that  each  row  consists  of  4  bytes  of  data. 
The  pattern  now  looks  like  this: 


$55  $55 
$55  $55 
$55  $55 
$55  $55 
$55  $55 
$55  $55 
$55  $55 
$55  $55 


$55  $55 
$55  $55 
$55  $55 
$55  $55 
$55  $55 
$55  $55 
$55  $55 
$55  $55 


$55  =  01010101 


To  load  the  pattern  in  the  system,  use  the  GPLoad  com- 
mand. To  load  this  particular  pattern  into  Group  2  and 
Buffer  1,  the  command  would  be: 

display  1b  2b  82  81   80  29   00   88  88    28  55  55  ...55    I  ENTER  I 


32  times 

number  of  bytes  (32) 
y  size  of  pattern  (8) 
x  size  of  pattern  (32) 
buffer  number 
group  number 
GPLoad  code 


3-30 


General  Commands  I  3 


When  making  a  pattern  using  4  colors,  a  pixel  is  made  up 
of  two  bits  instead  of  one.  This  means  that  the  pattern  con- 
sists of  64  bytes  instead  of  32.  The  diagram  below  shows 
the  bit  set  pattern  for  the  same  vertical  pattern  using  4 
colors: 

110011001100110011001100110011001100110011001100110011001100 
110011001100110011001100110011001100110011001100110011001100 
110011001100110011001100110011001100110011001100110011001100 
110011001100110011001100110011001100110011001100110011001100 
1100110011O0110011001100110011001100110011001100U0011001100 
110011001100110011001100110011001100110011001100110011001100 
110011001100110011001100110011001100110011001100110011001100 
110011001100110011001100110011001100110011001100110011001100 

When  the  binary  for  the  4x8  pixel  data  is  compressed  into 
byte  data,  notice  that  each  row  consists  of  8  bytes  of  data. 
The  pattern  now  looks  like  this: 


$CC  $CC 
$CC  $CC 
$CC  $CC 
$CC$CC 
$CC$CC 
$CC  $CC 
$CC  $CC 

$cc  $cc 


$cc  $cc  $cc 
$cc  $cc  $cc 
$cc  $cc  $cc 
$cc  $cc  $cc 
$cc  $cc  $cc 
$cc  $cc  $cc 
$cc  $cc  $cc 
$cc  $cc  $cc 


$cc  $cc  $cc 
$cc  $cc  $cc 
$cc  $cc  $cc 
$cc  $cc  $cc 
$cc  $cc  $cc 
$cc  $cc  $cc 

$CC  ICC  $cc 
$cc  $cc  $cc 


$CC  =  1100 


To  load  the  pattern  in  the  system,  use  the  GPLoad  com- 
mand as  described  for  the  2  color  example  but  specify  $40 
(64)  bytes  instead  of  $20  (32). 

•  When  making  a  pattern  using  16  colors,  a  pixel  is  made  up 
of  four  bits  instead  of  one.  This  means  that  the  pattern  con- 
sists of  128  bytes.  Each  line  in  the  bit  pattern  would  look 
like  this: 

111  10000... {repeat  pattern  for  16  total  sets}.. .11110000 

When  the  binary  for  the  8x8  pixel  data  is  compressed  into 
byte  data,  the  pattern  is  a  series  of  $F0. 

To  load  the  pattern  in  the  system,  use  the  GPLoad  com- 
mand and  specify  $80  (128)  bytes  as  the  size. 
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PutBlk  Put  Block 

Function:  Moves  a  GET/PUT  buffer,  previously  copied  from  the 
screen  or  loaded  with  GPLoad,  to  an  area  of  the  screen. 

Code:  IB  2D 

Parameters:  GRP  BFN  HBX  LBX  HBY  LBY 

HBX/LBX  =  x-location  of  block 

(upper  left  comer) 

HBY/LBY  =  y-location  of  block 


Notes: 


The  dimensions  of  the  block  were  saved  in  the  GET/PUT 
buffer  when  you  created  it.  OS-9  uses  these  dimensions 
when  restoring  the  buffer. 

The  screen  type  conversion  is  automatically  handled  by  the 
PutBlk  routine  in  the  driver. 

GET/PUT  buffers  cannot  be  scaled.  The  image  will  be 
clipped  if  it  does  not  fit  within  the  window. 
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ScaleSw  Scale  Switch 


Function:  Disables  and  enables  automatic  scaling.  Normally, 
automatic  scaling  is  enabled.  When  scaling  is  enabled,  coordi- 
nates refer  to  a  relative  location  in  a  window  that  is  propor- 
tionate to  the  size  of  the  window.  When  scaling  is  disabled, 
coordinates  passed  to  a  command  will  be  the  actual  coordi- 
nates for  that  type  of  screen  relative  to  the  origin  of  the 
window. 

Code:  IB  35 

Parameters:  BSW 

BSW  =  switch 

00  =  off 

01  =  on  (Default) 


Notes: 


A  useful  application  of  disabled  scaling  is  the  arrangement 
of  references  between  a  figure  and  text. 

All  coordinates  are  relative  to  the  window's  origin  (0,0). 
The  valid  range  for  the  coordinates: 

Scaling  enabled: 

y  =  0-191 
x  =  0-639 

Scaling  disabled: 

y  =  0-size  ofy  - 1 
x  =  0-size  ofx-1 
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Select  Window  Select 


Function:  Causes  the  current  process's  window  to  become  the 
active  (display)  window.  You  can  select  a  different  window  by 
using  the  form: 

display    1B   21    >/wmimber 

where  number  is  the  desired  window  number.  If  the  process 
that  executes  the  select  is  running  on  the  current  interactive 
(input/display)  window,  the  selected  window  becomes  the 
interactive  window,  and  the  other  window  becomes  passive. 

Code:  IB  21 

Parameters:  None 

Notes: 

•  The  keyboard  is  attached  to  the  process's  selected  window 
through  the  use  of  the  |  clear  |  key.  This  lets  you  input  data 
from  the  keyboard  to  different  windows  by  using  the  [  clear  | 
key  to  select  the  window. 

•  All  display  windows  that  occupy  the  same  screen  are  also 
displayed. 

•  The  device  window  which  owns  the  keyboard  is  the  current 
interactive  window.  The  interactive  window  is  always  the 
window  being  displayed.  Only  one  process  may  receive 
input  from  the  keyboard  at  a  time.  Many  processes  may  be 
changing  the  output  information  on  their  own  windows; 
however,  you  can  only  see  the  information  that  is  displayed 
on  the  interactive  window  and  any  other  window  on  the 
same  screen  as  the  interactive  window. 
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TCharSw  Transparent  Character  Switch 


Function:  Defines  the  character  mode  to  be  used  when  putting 
characters  on  the  graphics  screens. 

In  the  default  mode  (transparent  off),  the  system  uses  block 
characters  that  draw  the  entire  foreground  and  background  for 
that  cell. 

When  in  transparent  mode,  the  only  pixels  that  are  changed 
are  the  ones  where  the  character  actually  has  pixels  set  in  its 
font.  When  transparent  mode  is  off,  all  pixels  in  the  character 
block  are  set:  foreground  or  font  pixels  in  the  foreground  color 
and  others  in  the  background  color. 

Code:  IB  3C 

Parameters:  BSW 

BSW  =  switch 

00  =  off  (Default) 

01  =  on 
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All  drawing  commands  relate  to  an  invisible  point  of  reference 
on  the  screen  called  the  draw  pointer.  Originally,  the  draw- 
pointer  is  at  position  0,0.  You  can  change  the  position  by  using 
the  SetDPtr  and  RSetDPtr  commands  described  in  this  chapter. 
In  addition,  some  draw  commands  automatically  update  the 
draw  pointer.  For  example,  the  LineM  command  draws  a  line 
from  the  current  draw  pointer  position  to  the  specified  end  coor- 
dinates and  moves  the  draw  pointer  to  those  end  coordinates. 
The  Line  command  draws  a  line  but  does  not  move  the  pointer. 

Also,  note  that  all  draw  commands  are  affected  by  the  pattern 

and  logic  commands  described  in  Chapter  3. 

Do  not  confuse  the  draw  pointer  with  the  graphics  cursor.  The 
graphics  cursor  is  the  graphic  representation  of  the  mouse/joy- 
stick position  on  the  screen. 

In  this  chapter,  commands  that  use  relative  coordinates  (offsets) 
are  listed  with  their  counterparts  that  use  absolute  coordinates. 
For  example,  RSetDPtr  is  listed  under  SetDPtr. 
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Arc3P 


Draw  Arc 


Function:  Draws  an  arc  with  its  midpoint  at  the  current  draw 

pointer  position.  You  specify  the  curve  by  both  the  X  and  Y 
dimensions,  as  you  do  an  ellipse.  In  this  way,  you  can  draw 
either  elliptical  or  circular  arcs.  The  arc  is  clipped  by  a  line 
defined  by  the  (X01,Y01)  -  (X02.Y02)  coordinates.  These  coor- 
dinates are  signed  16  bit  values  and  are  relative  to  the  center 
of  the  ellipse.  The  draw  pointer  remains  in  its  original 
position. 

Code:  IB  52 

Parameters:  HBRx  LBRx  HBRy  LBRy  HX01  LX01  HY01 
LY01  HX02  LX02  HY02  LY02 

Notes: 


• 


The  resulting  arc  depends  on  the  order  in  which  you  specify 
the  line  coordinates.  Arc3P  first  draws  the  line  from  Point 
1  to  Point  2  and  then  draws  the  ellipse  in  a  clockwise 
direction. 

The  coordinates  of  the  screen  are  as  follows: 

-Y 


-X 1 . +x 


+  Y 
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Bar  Draw  Bar 

Function:  Draws  and  fills  a  rectangle  that  is  defined  by  the 
diagonal  line  from  the  current  draw  pointer  position  to  the 
specified  position.  The  box  is  drawn  in  the  current  foreground 
color.  The  draw  pointer  returns  to  its  original  location. 

Code:  IB  4A 

Parameters:  HBX  LBX  HBY  LBY 

RBar  Relative  Draw  Bar 

Function:  Draws  and  fills  a  rectangle  that  is  defined  by  the 
diagonal  line  from  the  current  draw  pointer  position  to  the 
point  specified  by  the  offsets.  The  box  is  drawn  in  the  current 
foreground  color.  The  draw  pointer  returns  to  its  original  loca- 
tion. This  is  a  relative  command. 

Code:  IB  4B 

Parameters:  HBXo  LBXo  HBYo  LBYo 
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BOX  Draw  Box 

Function:  Draws  a  rectangle  that  is  defined  by  the  diagonal 
line  from  the  current  draw  pointer  position  to  the  specified 
position.  The  box  is  drawn  in  the  current  foreground  color. 
The  draw  pointer  returns  to  its  original  location. 

Code:  IB  48 

Parameters:  HBX  LBX  HBY  LBY 

RBOX  Relative  Draw  Box 

Function:  Draws  a  rectangle  that  is  defined  by  the  diagonal 
line  from  the  current  draw  pointer  position  to  the  point  speci- 
fied by  the  offsets.  The  box  is  drawn  in  the  current  foreground 
color.  The  draw  pointer  returns  to  its  original  location.  This  is 
a  relative  command. 

Code:  IB  49 

Parameters:  HBXo  LBXo  HBYo  LBYo 
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Circle  Draw  Circle 

Function:  Draws  a  circle  of  the  specified  radius  with  the  cen- 
ter of  the  circle  at  the  current  draw  pointer  position.  The  cir- 
cle is  drawn  in  the  current  foreground  color.  The  draw  pointer 
remains  in  its  original  location. 

Code:  IB  50 

Parameters:  HBR  LBR 
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Ellipse  Draw  Ellipse 

Function:  Draws  an  ellipse  with  its  center  at  the  current  draw 
pointer  position.  The  X  value  specifies  the  horizontal  radius, 
and  the  Y  value  specifies  the  vertical  radius.  The  ellipse  is 
drawn  in  the  current  foreground  color.  The  draw  pointer 
remains  in  its  original  location.  This  is  a  relative  command. 

Code:  IB  51 

Parameters:  HBRx  LBRx  HBRy  LBRy 
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FFill  Flood  Fill 


Function:  Fills  the  area  where  the  background  is  the  same 
color  as  the  draw  pointer.  Filling  starts  at  the  current  draw 
pointer  position,  using  the  current  foreground  color.  The  draw 
pointer  returns  to  its  original  location.  This  is  a  relative 
command. 

Code:  IB  4F 

Parameters:  None 


4-7 


OS-9  Windowing  System 


Line 


Draw  Line 


Function:  Draws  a  line  from  the  current  draw  pointer  position 
to  the  specified  point,  using  the  current  foreground  color.  The 
draw  pointer  returns  to  its  original  location. 

Code:  IB  44 

Parameters:  HBX  LBX  HBY  LBY 

RLme  Relative  Draw  Line 

Function:  Draws  a  line  from  the  current  draw  pointer  position 
to  the  point  specified  by  the  x,y  offsets,  using  the  current  fore- 
ground color.  The  draw  pointer  returns  to  its  original  location. 
This  is  a  relative  command. 

Code:  IB  45 

Parameters:  HBXo  LBXo  HBYo  LBYo 
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LilieM  Draw  Line  and  Move 

Function:  Draws  a  line  from  the  current  draw  pointer  position 
to  the  specified  point,  using  the  current  foreground  color.  The 
draw  pointer  stays  at  the  new  location. 

Code:  IB  46 

Parameters:  HBX  LBX  HBY  LBY 

RLineM  Relative  Draw  Line  and  Move 

Function:  Draws  a  line  from  the  current  draw  pointer  position 

to  the  point  specified  by  the  offsets,  using  the  current  fore- 
ground color.  The  draw  pointer  stays  at  the  new  location.  This 
is  a  relative  command. 

Code:  IB  47 

Parameters:  HBXo  LBXo  HBYo  LBYo 
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Point  Draw  Point 

Function:  Draws  a  pixel  at  the  specified  coordinates,  using 
the  current  foreground  color. 

Code:  IB  42 

Parameters:  HBX  LBX  HBY  LBY 

RPoiIlt  Relative  Draw  Point 

Function:  Draws  a  pixel  at  the  location  specified  by  the  off- 
sets, using  the  current  foreground  color.  This  is  a  relative 
command. 

Code:  IB  43 

Parameters:  HBXo  LBXo  HBYo  LBYo 
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PlltGC  Put  Graphics  Cursor 


Function:  Puts  and  displays  the  graphics  cursor  at  the  speci- 
fied location.  The  coordinates  passed  to  this  command  are  not 
window- 
relative.  The  horizontal  range  is  0  to  639.  The  vertical  range 
is  0  to  191.  The  default  position  is  0,0. 

This  command  is  useful  for  applications  running  under  Grflnt 
so  that  you  can  display  a  graphics  cursor  under  Windlnt  even 
if  you  don't  want  mouse  control  of  the  cursor. 

Code:  IB  4E 

Parameters:  HBX  LBX  HBY  LBY 
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SetDPtr  Set  Draw  Pointer 

Function:  Sets  the  draw  pointer  to  the  specified  coordinates. 
The  new  draw  pointer  position  is  used  as  the  beginning  point 
in  the  next  draw  command  if  other  coordinates  are  not 
specified. 

Code:  IB  40 

Parameters:  HBX  LBX  HBY  LBY 

RSetDPtr  Relative  Set  Draw  Pointer 

Function:  Sets  the  draw  pointer  to  the  point  specified  by  the 
offsets.  The  new  draw  pointer  position  is  used  as  the  begin- 
ning point  in  the  next  draw  command  if  other  coordinates  are 
not  specified.  This  is  a  relative  command. 

Code:  IB  41 

Parameters:  HBXo  LBXo  HBYo  LBYo 
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Text  Commands 


The  text  commands  let  you  control  the  cursor's  position  and 
movement  and  also  the  way  text  prints  on  the  display.  These 
commands  can  be  used  on  either  text  or  graphics  windows. 


The  text  commands  are: 
Code  Description 


01 

Homes  the  cursor. 

02  xy 

Positions  cursor  to  xj.  Specify  coordinates  as 

(x  +  $20)and(y  +  $20). 

03 

Erases  the  current  line. 

04 

Erases  from  the  current  character  to  the  end  of 
the  line. 

05  20 

Turns  off  the  cursor. 

05  21 

Turns  on  the  cursor. 

06 

Moves  the  cursor  right  one  character. 

07 

Rings  the  bell. 

08 

Moves  the  cursor  left  one  character. 

09 

Moves  the  cursor  up  one  line. 

0A 

Moves  the  cursor  down  one  line. 

0B 

Erases  from  the  current  character  to  the  end  of 
the  screen. 

oc 

Erases  the  entire  screen  and  homes  the  cursor. 

0D 

Sends  a  carriage  return. 

IF  20 

Turns  on  reverse  video. 

IF  21 

Turns  off  reverse  video. 

IF  22 

Turns  on  underlining. 

IF  23 

Turns  off  underlining. 

IF  24 

Turns  on  blinking.1 
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Code 

Description 

IF  25 

Turns  off  blinking.1 

IF  30 

Inserts  a  line  at  the  current  cursor  position. 

IF  31 

Deletes  the  current  line. 

IB  3C  BSW 

See  TCharSw  in  Chapter  3.z 

IB  3D  BSW 

See  BoldSw  in  Chapter  3.2 

IB  3F  BSW 

See  PropSw  in  Chapter  3.2 

1  Blink  is  not  supported  for  text  on  graphics  screens. 

2  These  characteristics  are  supported  for  text  on  graphics 
screens  only. 


5-2 


Index 


active  window    3-34 
AND    3-21 
arc,  draw     4-2 

ARC3P    4-2 


buffers  (cont'd) 

screen  type    3-32 
size    3-32 
save  3-18 


background  color    3-2,  3-13 

BAR    4-3 

bar,  draw     4-3 

bar,  relative  draw     4-3 

BCOLOR    3-2 

bell,  ring    5-1 

blinking    5-1,  5-2 

off    5-2 

on    5-1 
boldface    3-3,5-2 
BOLDSW    3-3,5-2 
BORDER    3-4,3-26 
border  color    3-4,  3-13,  3-26 
BOX    4-4 
box,  draw    4-4 
box,  relative  draw    4-4 
buffer,  kill    3-20 
buffer,  load    3-19 
buffers    3-7,3-19 
buffers 

close    3-20 

define    3-7 

font    3-19 

get/put    3-19 

get/put    3-7 

patterns    3-29 
save    3-18 

group  numbers    3-7 

kill    3-20 

load    3-19 

logic    3-21 

pattern    3-29 

16-color    3-31 
2-color    3-30 
4-color     3-31 

pattern  array    3-29 

pattern  size    3-29 

put    3-32 

block     3-32 


carriage  return    5-1 
change  font    3-15 
character 

erase    5-1 

transparent    3-35 
CIRCLE    4-5 
circle,  draw    4-5 
close  buffer    3-20 
close  overlay  window    3-23 
close,  window    3-10,  3-23 
color    3-26 

background    3-2,  3-13 

border    3-4,3-13,3-26 

composite    3-27 

default    3-6 

foreground    3-13,3-14, 
3-26 

graphics    3-6 

high-resolution    3-6 

palette     3-26 

RGB     3-26 

VDG-emulation  3-6 
command  parameters  2-1 
commands 

drawing    2-1,  4-1 

general    2-1,  3-1 

text    2-1,  5-1 
composite  colors    3-27 
create  windows 

device     1-2 

overlay     1-4 
current  window    3-13,  3-34 
cursor    3-17 

home    5-1 

graphics    3-17 
put    4-11 

move    5-1 

off    5-1 

on    5-1 
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cursor  (confd) 

position     5-1 

set    3-17 
CWAREA    3-5 

default  color    3-6 

default  windows    1-3 

DEFCOLR    3-6 

define  buffers    3-7 

define  device  windows    3-12 

delete  line    5-2 

device  descriptors    1-1,  3-12 

device  windows    1-1 

background  color    3-13 

border  color    3-13 

color 

background    3-13 
border    3-13 
foreground    3-13 

define    3-12 

end    3-10 

foreground  color    3-13 

keyboard    3-34 

location    3-13 

process  window    3-13 

protect    3-11 

select    3-34 

set    3-12 
DFNGPBUF    3-7 
DISPLAY    1-2,2-1,3-12 
draw  pointer    4-1 

relative  set    4-12 

set    4-12 
draw 

arc    4-2 

bar    4-3 

bar,  relative    4-3 

box    4-4 

box,  relative    4-4 

circle    4-5 

ellipse    4-6 

fill    4-7 

flood  fill    4-7 

line    4-8 

line  and  move    4-9 


draw  {cont'd) 

line  and  move, 
relative     4-9 

line,  relative    4-8 

point    4-10 

point,  relative    4-10 

pointer    4-1 
drawing  commands    4-1 
DWEND    3-10 
DWPROTSW    3-11 
DWSET    1-1,1-2,3-12 

ELLIPSE    4-6 

ellipse,  draw    4-6 

end  overlay  window    3-23 

end  window    3-10,  3-23 

erase  character    5-1 

erase  line    5-1,  5-2 

erase  screen    5-1 

erase  to  end  of  screen    5-1 

escape  sequence    1-2 

FCOLOR    3-14 

FFILL    4-7 

fill,  draw    4-7 

flood  fill,  draw    4-7 

FONT    3-15 

font    3-12,3-15,3-19 

bit  map    3-15 

boldface    3-3,5-2 

change    3-15 

current    3-15 

data    3-15 

load    3-19 

order    3-15 

proportional    3-15,  3-28, 
5-2 
font  bit  map    3-15 
font  data    3-15 
font  load    3-19 
font  order    3-15 
foreground  color    3-13,  3-14, 
3-26 

GCSET    3-17 


Index 


general  commands    2-1,  3-1 

LINE    4-8 

get/put  buffers 

line 

close    3-20 

delete    5-2 

define    3-7 

draw    4-8 

font    3-19 

erase    5-1,  5-2 

group  numbers    3-7 

insert    5-2 

kill    3-20 

relative  draw    4-8 

load    3-19 

line  and  move,  draw    4-9 

logic    3-21 

line  and  move,  relative  draw 

patterns    3-29 

4-9 

put    3-32 

LINEM    4-1,4-9 

save    3-18 

load  get/put    3-19 

GETBLK    3-18 

load  font    3-15,  3-19 

GPLOAD    3-9,  3-15,  3-19,  3- 

location,  window    3-13 

32 

logic  operations    3-21,  4-1 

graphic  patterns    3-29 

logic  set    3-21 

graphics 

LSET    3-21 

boldface    3-3 

colors    3-6 

memory    1-1, 3-12 

cursor    3-17,  4-11 

MONTYPE    3-6 

put    4-11 

move  cursor    5-1 

set    3-17 

font,  proportional    3-28 

open  windows 

transparent    3-35 

device    1-2 

group  numbers    3-7,  3-8 

overlay    1-4 

Grp_Clip    3-8 

OR    3-21 

Grp_Fnt    3-8 

overlay  window    1-1,  1-2,  3-23, 

Grp_Pat2    3-8 

3-24 

Grp    Pat4    3-8 

overlay  window 

GrpJPat6    3-8 

end    3-23 

Grp__Ptr    3-8 

no-save    3-24 

save    3-24 

high-resolution,  colors    3-6 

select    3-34 

home  cursor    5-1 

set    3-24 

size    3-24 

I$ATTACH    3-10 

stacked    3-25 

immortal  shell     1-3 

OWEND    3-23 

INIZ     1-2,  3-10,  3-12 

OWSET    1-4,3-24 

insert  line    5-2 

interactive  window    3-34 

PALETTE    3-26 

palette  colors    3-26 

KILBUF    3-20 

parameters,  command    2-1 

kill  buffer    3-20 

pattern    3-29,  4-1 

16-color    3-31 

2-color     3-30 

3 
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pattern  {cont'd) 

set 

4-color    3-31 

device  window    3-12 

array     3-29 

draw  pointer    4-12 

size    3-29 

draw  pointer,  relative 

POINT    4-10 

4-12 

point,  draw    4-10 

overlay  window    3-24 

point,  relative  draw    4-10 

SETDPTR    4-1,4-12 

pointer,  draw    4-1 

SETSTAT    3-6 

position  cursor    5-1 

SHELL    1-3 

process  window    3-13 

shell,  fork     1-3 

proportional  characters    3-28, 

stacked  overlay  windows    3-25 

5-2 

proportional  font    3-28 

TCHARSW    3-35,5-2 

PROPSW    3-28,5-2 

text  commands    5-1 

protect  device  windows    3-11 

text 

PSET    3-29 

boldface    3-3,5-2 

put  block     3-32 

proportional    3-28,  5-2 

put  buffer    3-32 

transparent  character    3-35, 

screen  type    3-32 

5-2 

size    3-32 

put  graphics  cursor    4-11 

underline 

PUTBLK    3-18,3-19,3-32 

off    5-1 

PUTGC    4-11 

on    5-1 

RBAR    4-3 

video,  reverse    5-1 

RBOX    4-4 

reverse  video    5-1 

WCREATE    1-2 

RGB  colors    3-26 

windows    1-1 

ring  bell     5-1 

background  color    3-2, 

RLINE    4-8 

3-13 

RLINEM    4-9 

boldface    3-3,  5-2 

RPOINT    4-10 

border  color    3-4,  3-13, 

RSETDPTR    4-1,4-12 

3-26 

buffers    3-7,3-19 

save,  get/put    3-18 

kill    3-20 

save  window    3-18 

load    3-19 

SCALESW    3-33 

patterns    3-29 

scaling     3-33 

put    3-32 

scaling,  automatic    3-33 

close    3-10,  3-23 

scaling  coordinates    3-33 

color    3-26 

screen  type    3-12 

background    3-2, 

screen,  erase    5-1 

3-13 

SELECT    3-34 

border    3-4,  3-13, 

select  window    3-34 

3-26 

4 

composite    3-27 

Index 


windows  {conifd) 

default    3-6 
foreground     3-13, 

3-14,  3-26 
RGB    3-26 

current    3-13 

cursor    3-17 

default     1-3 

default  color    3-6 

device    1-1 

define    3-12 
end    3-10 
opening     1-2 
protect    3-11 
select    3-34 
set    3-12 

device  descriptors     1-1, 
3-12 

end    3-10 

fonts    3-15,3-19 

foreground  color    3-13, 
3-14,  3-26 

graphics  cursor    3-17, 
4-11 

interactive    3-34 

keyboard    3-34 

location    3-13 

logic  operations    3-21 

maximum     1-1 


windows  {cont'd) 

memory     1-1,  3-12 

overlay    1-1,  1-2,  3-23, 
3-24 

end    3-23 
no-save    3-24 
opening    1-4 
save    3-24 
select    3-34 
set    3-24 
size    3-24 
stacked     3-25 

process  window    3-13 

process    3-13 

protect    3-11 

put  buffer    3-32 

save    3-18 

scaling    3-33 

screen  type    3-12 

select    3-34 

size    3-5 

transparent  mode    3-35, 
5-2 

type    1-1 

work  area    3-5 
work  area    3-5 

XOR    3-21 
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active  processes.  Operations  that  the  system  is  currently 
executing. 

active  state.  An  operating  or  working  condition.  A  procedure 
in  an  active  state  is  processing  data  and  not  waiting  for  another 
procedure  to  end. 

address.  A  number  that  identifies  a  location  in  your  comput- 
er's memory. 

age.  A  count  of  the  number  of  switches  (process  changes)  the 
system  has  made  since  a  process's  last  time  slice. 

anonymous  directory.  A  directory  referenced  by  its  hierarchi- 
cal position  using  the  period  (.)  character.  One  period  refers  to 
the  current  directory.  Two  periods  refer  to  the  parent  of  the  cur- 
rent directory,  and  so  on. 

application  program.  A  process  or  group  of  processes 
designed  to  accomplish  specific  tasks,  such  as  word  processing, 
data  management,  game  playing,  and  so  on. 

argument.  Data  you  supply  to  a  process  or  command  for  it  to 
evaluate. 

array.  Data  arranged  so  that  each  item  is  located  by  its  row 
and  column  position.  Single-dimensioned  arrays  have  one  or  more 
rows  and  one  column.  Multi-dimensioned  arrays  have  one  or 
more  rows  and  two  or  more  columns. 

ASCII  code.  American  Standard  Code  for  Information  Inter- 
change. A  method  of  defining  alphabetic  and  numeric  characters 
and  other  symbols  by  giving  each  a  unique  value.  For  instance, 
the  ASCII  value  for  A  is  65,  and  the  ASCII  value  for  B  is  66. 

assembler.  A  program  that  produces  machine  code  from  source 
code  (code  from  a  low-level  computer  language). 

assembly  language.  A  system  for  coding  computer  instruc- 
tions to  perform  tasks.  You  can  use  assembly  language  code  to 
directly  manipulate  data  within  a  computer;  therefore,  assembly 
language  needs  less  interpretation  than  higher  level  languages 
like  BASIC  or  Pascal. 

attribute.    See  file  attribute. 
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background  processing.  Executing  one  or  more  procedures 
and  at  the  same  time  continuing  to  operate  in  OS-9  or  in 
another  procedure. 

backup.  An  identical  copy  of  the  contents  of  one  disk  on 
another  disk. 

base.  The  lowest  value  allowed  in  a  function  or  operation.  For 
instance,  BASIC09  allows  a  base  value  of  1  for  array  structures 
unless  you  indicate  otherwise. 

batch  file.    See  procedure  file. 

baud.  Bits-per-second.  A  unit  for  measuring  the  speed  of  data 
flow  between  devices. 

binary.  A  numbering  system  using  only  two  digits,  0  and  1.  In 
this  system,  shifting  the  position  of  a  digit  to  the  left  raises  the 
value  of  the  digit  by  the  power  of  2.  For  instance,  1  is  the  binary 
equivalent  of  1,  10  =  2,  100  =  4,  1000  =  16,  and  so  on. 

bit.  The  smallest  unit  of  a  computer's  memory.  Eight  bits  form 
a  byte.  Each  bit  can  have  a  value  of  either  0  or  1. 

bit  map.  A  storage  area  of  256  bytes.  Each  bit  represents  one 
page  (256  bytes)  of  your  computer's  memory.  If  a  bit  is  set 
(equals  1)  then  its  associated  memory  page  is  allocated.  If  a  bit 
is  reset  (equals  0)  then  its  associated  memory  page  is  free. 

block.     A  group  of  data,  often  comprising  256  bytes. 

block-oriented  device.  A  device  that  receives  data,  sends 
data,  or  both,  in  groups  of  256  bytes. 

Boolean  logic.  A  binary  type  of  algebra  developed  by  George 
Boole. 

Boolean  data  type.  A  type  of  variable  that  can  have  only  two 
values,  True  or  False.  Boolean  data  types  usually  store  the 
results  of  comparisons,  such  as:  is  A  greater  than  B  (A>B),  does 
YequalX(Y  =  X),andsoon. 

boot.    The  process  of  loading  and  initializing  OS-9. 

bootfile.  A  disk  file  containing  the  necessary  information  and 
instructions  to  load  and  execute  the  OS-9  system. 

bootlist.  A  disk  file  containing  a  list  of  modules  to  be  loaded 
during  an  OS-9  boot. 
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bootstrap  module.  A  program  that  contains  the  code  neces- 
sary to  initialize  OS-9. 

border.  An  area  around  a  screen  or  window  that  defines  the 
boundaries  of  the  screen  or  window. 

branch.  To  leave  one  routine  and  begin  execution  of  another 
routine  within  a  program  or  procedure. 

breakpoints.  Locations  in  a  program  or  procedure  at  which 
you  want  execution  to  pause. 

buffer.  A  temporary  storage  area  through  which  OS-9  trans- 
fers data. 

byte.  A  unit  of  computer  memory  storage  that  contains  a  value 
in  the  range  0-255. 

byte  data  type.  A  numeric  type  of  variable  that  can  contain 
unsigned  eight-bit  integer  data  (in  the  range  0-255  decimal). 

call.  (1)  To  transfer  execution  to  another  routine,  then  return 
to  the  calling  procedure  with  obtained  values  intact  and  avail- 
able for  use  by  the  calling  routine.  (2)  A  built-in  OS-9  routine 
that  performs  a  system  function. 

CC3Disk.    The  floppy  diskette  driver  module. 

CC3IO.    The  system  input/output  driver. 

chaining.  A  process  of  calling  and  turning  over  system  control 
to  a  new  procedure. 

checksum.  A  value  calculated  from  the  contents  of  a  file  or 
module  that  the  system  can  later  use  to  verify  whether  the  con- 
tents of  the  file  or  module  are  uncorrupted. 

child  or  child  process.  A  process  begun  from  another  (par- 
ent) process. 

close.    The  process  of  deallocating  the  path  to  a  device  or  file. 

cluster.  A  group  of  sectors.  In  OS-9  for  the  Color  Computer,  a 
cluster  consists  of  only  one  sector. 

code.  Numeric  data  that  can  be  used  by  a  computer  to  perform 
a  task. 

command.     The  name  of  an  OS-9  program  or  function. 
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command  line.  One  or  more  commands  with  all  their  parame- 
ters, options,  and  modifiers. 

command  modifiers.  Data  or  values  appended  to  a  command 
that  change  the  way  the  command  functions. 

command  options.  Data  that  you  can  include  in  a  command 
line  to  specify  the  way  the  command  functions. 

command  parameters.  Data  or  values  appended  to  a  com- 
mand that  define  or  customize  the  command. 

command  separator.  A  semicolon.  You  can  use  a  semicolon  to 
separate  several  commands  on  the  same  command  line. 

compile.  To  create  machine  language  code  (object  code)  from  a 
program  written  with  a  computer  language.  Also  to  translate 
high  level  code  (from  a  high  level  language  such  as  BASIC)  into 
low  level  code  (code  that  is  like  machine  language). 

complement.  A  value  that  is  derived  by  subtracting  a  number 
from  a  constant.  For  example,  the  10s  complement  of  4  is  6.  In 
binary,  a  value  is  complemented  by  changing  all  the  1  digits  to  0 
and  all  the  0  digits  to  1,  then  adding  1  to  the  least  significant 
(rightmost)  digit. 

complex  data  structure.  A  group  of  data  that  contains  two  or 
more  types  of  data  structures.  See  data  structure. 

constant.  A  value  or  block  of  data  that  is  fixed  (does  not 
change  during  the  run  of  a  program  or  procedure). 

CPU.  Central  Processing  Unit.  An  integrated  circuit  (chip) 
that  controls  the  operation  of  a  computer. 

current  directory.  The  directory  in  which  OS-9  looks  for  data 
files  or  stores  data  files  unless  you  specify  otherwise. 

current  line.  When  editing,  the  line  on  which  the  editing  cur- 
sor or  pointer  is  located. 

cursor  (text).  A  colored  box  that  shows  where  the  next  charac- 
ter is  to  appear  on  the  screen.  A  text  cursor  appears  on  both  text 
and  graphics  windows  or  screens. 

cyclic  redundancy  check  (CRC).  A  value  the  system  calcu- 
lates from  the  data  stored  in  a  module.  The  system  calculates  a 
new  value  each  time  it  attempts  to  load  the  module.  If  the  new 
value  and  the  old  CRC  are  not  the  same,  the  system  cannot  load 
the  module. 
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cylinder.  A  disk  track  that  includes  both  sides  of  a  disk.  See 
also  track. 

DAT.  Dynamic  address  translation.  The  memory  management 
system  used  by  OS-9  Level  Two. 

data  directory.  The  directory  in  which  OS-9  automatically 
saves  files  unless  you  specify  otherwise. 

data  structure.    A  unit  of  data,  organized  for  access. 

data  type.  A  method  for  representing  data,  such  as  character 
(ASCII  value),  integer  (whole  number),  or  real  (floating  point 
number). 

deadlock.    See  deadly  embrace. 

deadly  embrace.  A  situation  in  which  two  processes  attempt 
to  gain  control  of  the  same  disk  areas  at  the  same  time. 

debug.    To  find  and  correct  program  errors. 

decompile.  To  translate  machine  language  code  into  a  com- 
puter language  code. 

delimiter.  A  character  that  divides  items.  For  instance,  in 
OS-9,  the  semicolon  is  a  delimiter  that  divides  two  commands  on 
the  same  line. 

descriptor.    See  device  descriptors. 

device.  A  data  source,  destination,  or  both.  OS-9  devices  can 
exist  in  your  computer's  memory  (such  as  a  window  or  a  RAM 
disk),  or  they  can  be  external  equipment  (such  as  a  printer  or 
disk  drive). 

device  descriptors.  Small  tables  that  define  a  device,  its 
name,  its  driver,  and  its  file  manager.  Device  descriptors  also 
contain  port  initialization  data  and  port  address  information. 

device  drivers.  Modules  that  handle  basic  input/output  func- 
tions for  specific  devices.  Each  device  you  use  with  your  computer 
must  have  its  own  driver  to  interpret  the  code  you  send  it. 

device  name.  A  unique  system  word  for  a  device.  The  name  for 
disk  Drive  0  is  /DO,  the  name  for  Window  1  is  /Wl,  and  so  on. 

device  table.    See  device  descriptor. 
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device  window.  An  OS-9  device  from  which  you  can  run  a 
program  or  utility.  Access  device  windows  in  the  same  manner 
as  you  do  other  devices.  Each  device  window  has  its  own  input 
and  output  buffers.  Refer  to  windows  using  device  names  (AV  fol- 
lowed by  a  number),  such  as  AVI,  AV2,  AV3,  and  so  on. 

directory.  A  file  in  which  OS-9  stores  a  list  of  other  files, 
including  their  names,  locations  on  the  disk,  attributes,  and  so 
on. 

disk  allocation  map.  Logical  Sector  Number  1  on  a  disk.  The 
data  in  LSN1  indicates  which  sectors  are  allocated  to  files  and 
which  sectors  are  free. 

double  click.  To  press  and  release  the  mouse  button  twice  in 
quick  succession  when  the  pointer  is  over  the  desired  location. 

drag.  To  hold  down  the  mouse  button  and  move  the  mouse  to  a 
new  position  before  releasing  the  button. 

draw  pointer.  An  indicator  that  determines  where  the  next 
graphics  draw  command  will  begin  unless  you  specify  otherwise. 

driver.    See  device  driver. 

dump.  To  write  the  contents  of  a  video  screen,  a  memory  loca- 
tion or  a  file  to  another  terminal,  memory  location,  or  file. 

echo.  To  cause  data  being  sent  to  one  device  to  go  to  another 
device,  as  well. 

edit.  To  change  the  data  or  values  in  a  file  or  in  your  comput- 
er's memory. 

edit  buffer.  An  alternate  workspace  for  the  OS-9  Macro 
Editor. 

edit  macro.  A  series  of  commands  you  can  execute  with  only  a 
single  command. 

edit  pointer.  An  indicator  that  determines  where  the  next  edit 
command  is  to  operate  unless  you  specify  otherwise. 

editor.  A  program  that  provides  special  commands  to  aid  you 
in  changing  the  contents  of  a  file. 

error  code.  A  code  that  OS-9  displays  when  it  cannot  under- 
stand what  you  want  it  to  do  or  when  your  computer  or  a  periph- 
eral malfunctions.  Use  the  displayed  code  number  to  look  up  a 
description  of  the  error. 


1-6 


OS -9  Gbssary 


error  path.  The  route  through  which  OS-9  sends  error  codes 
and  other  information  to  display  on  the  screen.  The  error  path  is 
designated  as  Path  Number  2. 

error  trap.  A  routine  in  a  procedure  that  checks  for  an  error 
and  provides  an  alternate  action  (other  than  terminating  execu- 
tion and  displaying  a  system  error  message). 

executable  file.  A  program  file  that  you  can  run  by  typing 
and  entering  its  filename. 

execute.  To  start  a  procedure,  program,  or  command  (cause  it 
to  run). 

execution  directory.  The  disk  directory  that  contains  your 
system's  command  files. 

execution  modifiers.     See  command  modifiers. 

execution  offset.  The  location  in  a  program  or  subroutine  at 
which  execution  begins,  calculated  from  the  beginning  of  the 
module. 

expressions.  Data  items  joined  by  arithmetic  operators.  See 
also  operator. 

expression  stack.  A  memory  location  in  which  BASIC09 
stores  temporary  results  while  it  evaluates  an  expression. 

file.  (1)  A  block  of  information  your  computer  uses  for  a  partic- 
ular function  or  program.  A  file  can  contain  an  operating  sys- 
tem, a  language,  an  application  program,  or  text.  (2)  A  collection 
of  associated  records,  such  as  information  about  each  book  in  a 
library. 

file  attribute.  Data  that  identifies  a  file,  for  instance  its  size, 
security  status,  language  type,  and  so  on. 

file  locking.  Protecting  a  file  to  ensure  that  one  process  does 
not  change  it  while  another  process  is  using  it. 

file  pointer.  An  indicator  that  determines  where  in  a  file  the 
next  read  or  write  operation  is  to  occur  unless  you  or  the  system 
indicates  otherwise. 

file  security.  A  set  of  attributes  that  determines  who  can  use 
a  file  and  in  what  manner. 

filename.  A  set  of  characters  that  uniquely  identifies  and 
locates  a  block  of  data  stored  on  a  disk. 
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filter.  To  alter  data  in  some  manner  as  it  passes  between  two 
devices  or  between  two  memory  locations. 

flag.  A  symbol  or  value  that  indicates  when  a  certain  condition 
exists  in  a  procedure. 

font.  A  character  set.  A  group  of  alphabetic  and  numeric  char- 
acters and  other  symbols  of  a  particular  style  and  shape. 

foreground.  (1)  An  OS-9  task  that  takes  priority  over  other 
concurrently  running  tasks.  (2)  Characters  or  designs  on  a 
screen  or  window. 

fork.  The  process  of  initializing  one  procedure  from  another 
procedure. 

format.  To  magnetically  organize  a  diskette  so  that  the  com- 
puter can  use  it  to  store  data. 

function.  In  BASIC09,  an  operation  that  BASIC  performs  on 
data.  A  function  always  returns  (produces)  a  value  of  some  type. 

Get/Put  buffer.  A  buffer  in  which  you  or  the  system  can  store 
fonts,  screen  patterns,  graphic  displays,  overlay  windows,  and 
other  recallable  data.  The  system  allocates  Get/Put  buffers  in  8- 
kilobyte  blocks. 

getstat.  An  OS-9  routine  that  gets  (returns)  the  state  or  status 
of  a  specific  system  operation. 

global  variable.  A  variable  that  is  available  to  all  procedures 
and  routines  in  a  program. 

graphics.  An  arrangement  of  elements  (lines,  dots,  and  so  on) 
on  your  computer's  screen. 

graphics  cursor.  An  indicator  (either  visible  or  invisible)  that 
determines  where  the  next  graphic  function  is  to  occur  on  the 
screen  unless  you  or  a  program  specifies  otherwise.  In  applica- 
tions, you  often  move  the  graphics  cursor  using  a  mouse. 

graphics  pointer.    See  graphics  cursor. 

graphics  screen.  A  screen  in  which  all  pixels  are  represented 
by  bits  in  a  memory  map.  You  create  images  on  the  screen  by 
manipulating  the  bits  using  special  OS-9  or  computer  language 
commands. 
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graphics  window.  A  window  created  on  a  graphics  screen. 
%u  can  display  both  graphics  (drawn  images)  and  text  on  a 
graphics  window.  The  text  generated  on  a  graphics  window/ 
screen  uses  software  fonts  that  you  or  the  system  must  load  into 
memory. 

group.  An  organization  of  related  data  or  files.  For  instance, 
OS-9's  graphics  buffers  are  organized  into  groups  that  you  refer- 
ence by  number. 

hardware.  The  physical  parts  of  your  computer,  including  its 
disk  drives,  keyboard,  integrated  circuits  (chips),  and  so  on. 

header.  Data  located  at  the  beginning  of  a  file  or  module  to 
identify  its  type,  size,  verification  values,  and  so  on. 

hexadecimal.  A  number  system  to  a  base  of  16  (using  16  dig- 
its). Hexadecimal  digits  are  0,  1,  2,  3,  4,  5,  6,  7,  8,  9,  A,  B,  C^D, 
E,  and  F.  Shifting  a  hexadecimal  digit  one  place  to  the  left 
causes  its  value  to  be  multiplied  by  16. 

high  order  bit.  The  most  significant  or  leftmost  bit  in  a  byte. 
If  the  high  order  bit  is  0,  it  represents  a  value  of  0.  If  the  high 
order  bit  is  1,  it  represents  a  value  of  128. 

I/O.    Input/Output. 

identification  sector.  Logical  Sector  Number  0  on  a  disk. 
LSNO  contains  a  description  of  the  physical  and  logical  organiza- 
tion of  a  disk. 

immortal  shell.  An  OS-9  shell  that  does  not  die  on  receiving 
an  EOF  signal  (such  as  when  you  press  [  ctrl  ||  break]). 

integer  data  type.  A  type  of  variable  that  can  store  whole 
numbers  in  the  range  -32768  to  32767. 

interactive  window.  A  window  that  is  getting  input  from  the 
keyboard.  This  window  is  currently  on  the  displayed  screen. 

interface.  To  link  devices  or  modules  together  in  order  to 
transfer  data. 

internal  integrity  check.  A  system  of  internal  values  that 
OS-9  can  use  to  make  certain  that  its  system  modules  and  func- 
tions are  accurate. 

IOMAN.  The  input/output  manager  that  provides  common  pro- 
cessing for  all  input/output  operations. 


1-9 


OS-9  Gbssary 


IRQ.  Interrupt  request.  A  signal  that  causes  the  execution  of 
one  process  to  halt  and  the  execution  of  another  process  to  begin. 
The  system  retains  the  values  of  the  first  process  so  that  it  can 
later  continue  its  execution. 

kernel.  OS-9  software  that  supervises  the  OS-9  system  and 
provides  basic  system  services,  such  as  multitasking  and  memory 
management,  and  that  links  all  system  modules. 

key  sequence.  Two  or  more  keys  you  press  at  the  same  time  to 
produce  a  specific  function. 

keyboard  mouse.  An  OS-9  function  that  lets  you  use  the  key- 
board arrow  keys  instead  of  an  external  mouse  device.  Press 
I  ctrl  [|  clear]  to  toggle  the  keyboard  mouse  on  and  off. 

keyword.    A  command  name. 

kill.    Terminate  the  execution  of  a  process. 

kilobyte.    1024  bytes. 

link.    To  make  a  module  available  to  a  process. 

link  count.  The  number  of  processes  using  a  module.  When  a 
module's  link  count  reaches  0,  OS-9  deallocates  the  module. 

load.  To  transfer  data  from  an  external  device  into  your  com- 
puter's memory. 

local  variable.  A  variable  that  can  be  used  by  only  the  proce- 
dure or  routine  in  which  it  resides. 

locked.    See  file  locking. 

lockout.    See  file  locking. 

log  in.  To  initiate  the  necessary  procedure  to  operate  OS-9 
from  a  separate  terminal  (type  in  a  user  name  and  password). 

logical  address.  An  offset  address.  An  address  that  is  num- 
bered from  the  beginning  of  a  block  rather  than  from  the  begin- 
ning of  memory,  a  module,  or  other  storage  area. 

logical  sectors.  Sectors  that  OS-9  or  a  program  references  in 
numeric  order,  regardless  of  their  actual  physical  location  on  a 
disk. 

loop.  A  sequence  of  BASIC09  commands  that  execute  repeat- 
edly a  specified  number  of  times  or  until  a  specific  condition 
occurs  to  terminate  the  execution. 
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macro.  A  series  of  commands  you  can  execute  with  only  a  sin- 
gle command  name. 

map.    See  memory  map. 

mask.  A  pattern  of  bits  that  you  use  in  combination  with  a 
logical  operator  to  change  specified  data  selectively  —  reversing 
certain  bits  without  affecting  the  others. 

megabyte.    One  million  bytes. 

memory.  The  portion  of  your  computer  that  stores  data  and 
values. 

memory  management.  Assigning  and  mapping  memory  to 
keep  track  of  modules  (processes  and  data)  and  their  uses. 

memory  map.  A  chart  depicting  the  use  of  your  computer's 
memory  by  the  operating  system. 

menu.  A  screen  display  from  which  you  select  an  action  for 
your  computer. 

microprocessor.  An  integrated  circuit  (chip)  that  controls  the 
basic  operation  of  your  computer. 

mode.    A  particular  function  of  a  program  or  system. 

modem.  Modulator/demodulator.  A  device  to  prepare  signals 
for  transmission  through  telephone  lines  and  to  reverse  the  pro- 
cess after  transmission. 

modifier.    See  command  modifier. 

module.  An  OS-9  program  or  block  of  data  residing  in  your 
computer's  memory. 

module  body.  A  module's  code  (program  or  data),  including 
the  module  name. 

module  directory.  A  table  in  your  computer's  memory  that 
lists  all  the  modules  residing  in  memory. 

module  header.  Code  that  resides  at  the  beginning  of  all  mod- 
ules and  that  contains  information  about  the  module,  including 
size,  type,  attributes,  storage  requirements,  and  its  execution 
starting  address. 

monitor.    The  video  display  device  connected  to  your  computer. 
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mouse.  A  device  you  use  to  control  a  pointer  on  the  display 
screen.  In  application  programs,  you  can  often  use  a  mouse  to 
indicate  functions  you  want  to  initiate. 

multi-programming.  A  method  of  computer  operation  in 
which  the  system  allocates  slices  of  execution  time  to  more  than 
one  process  in  order  to  execute  them  concurrently. 

multi-tasking.  Executing  more  than  one  process  at  the  same 
time. 

multi-user.  A  system  that  lets  more  than  one  person  access  its 
functions  at  the  same  time. 

nesting.  Incorporating  one  structure  into  another  structure  of 
the  same  type.  Both  procedures  then  retain  their  individual 
identities. 

non-shareable  file.  A  file  or  module  that  can  be  used  by  only 
one  procedure  or  user  at  one  time. 

null  string.  A  string  variable  that  does  not  contain  a  value 
(has  a  length  of  0  characters). 

object  code.    Machine  language  instructions. 

offset.  The  difference  between  a  location  and  a  beginning  loca- 
tion. For  instance,  you  can  tell  some  BASIC09  graphics  functions 
to  begin  operation  at  a  location  that  is  offset  from  the  current 
draw  pointer  position. 

operand.  A  value  that  is  used  or  manipulated  during  an  oper- 
ation or  during  the  execution  of  an  instruction. 

operating  system.  A  set  of  associated  programs  that  carry 
out  your  commands. 

operator.  A  symbol  or  word  that  signifies  some  action  to  be 
performed  on  specified  data. 

options.    See  command  options. 

output  path.  The  route  through  which  the  system  sends  data 
from  one  device  to  another. 

overflow.  A  condition  in  which  a  storage  space  is  not  large 
enough  to  contain  the  data  sent  to  it. 

overlay.  A  condition  in  which  programs  or  modules  in  a  com- 
puter's memory  are  replaced  with  other  data. 
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overlay  window.  A  window  opened  or  placed  on  top  of  a  device 
window. 

overwrite.    To  replace  data  with  other  data. 

owner.  An  entity  that  has  control  over  a  file,  module,  or 
process. 

pack.    To  compile  a  BASIC09  procedure.  See  compile. 

padding.  Adding  spaces  to  a  string  or  unit  of  data  to  make  it 
a  specific  length. 

page.    In  your  computer's  memory,  a  block  of  256  bytes. 

paint.    To  fill  all  or  a  portion  of  the  screen  with  a  color. 

palette.  A  register  that  contains  a  numeric  code  representing  a 
color  or  shade. 

parameters.    See  command  parameters. 

parent  or  parent  process.  A  process  that  forks  (starts) 
another  process  (a  child  process). 

parity.  A  system  in  which  all  binary  numbers  of  a  code  are 
converted  to  either  even-bit  numbers  (an  even  number  of  Is  and 
Os)  or  odd-bit  numbers  (an  odd  number  of  Is  and  Os). 

parse.    To  search  through  a  list  or  sequence  of  data. 

Pascal.    A  high-level  computer  language. 

pass  by  value.  When  BASIC09  passes  a  value  from  one  proce- 
dure to  another  by  evaluating  a  constant  or  expression  and  plac- 
ing the  result  in  temporary  storage  to  be  accessed  by  the  second 
procedure. 

pass  by  reference.  When  BASIC09  passes  a  variable  from  one 
procedure  to  another  by  providing  the  second  procedure  with  the 
address  of  the  variable's  storage. 

passive  window.  Any  window  that  is  not  receiving  input  from 
the  keyboard.  A  process  can  be  running  on  a  passive  window 
provided  that  the  process  is  getting  its  input  from  a  source  other 
than  the  keyboard. 
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pathlist.  The  route  from  one  position  in  a  disk's  directory  to 
another  directory  or  file. 

pel.    See  pixel. 

peripherals.  Devices  connected  to  your  computer,  such  as 
printers,  disk  drives,  and  so  on. 

permission.  The  attributes  of  a  file  or  module  that  determine 
who  can  use  the  file  or  module  and  in  what  manner. 

physical  sectors.  The  actual  arrangement  of  sectors  on  a 
disk's  surface,  regardless  of  any  internal  organization  by  OS-9. 

pipe.  A  function  in  which  the  output  of  one  process  becomes 
the  input  of  another  process. 

pipeline.  A  series  of  commands,  each  of  which  passes  the 
results  of  its  operations  to  the  next  command  in  the  series. 

PIPE  MAN.  The  pipe  file  manager.  Pipes  are  memory  buffers 
acting  as  files  to  transfer  data  between  processes. 

pixel.  The  smallest  area  of  a  display  screen  that  can  be  manip- 
ulated (turned  off  or  on). 

pointer.  An  indicator  that  determines  a  location  in  memory,  in 
a  file,  or  on  the  screen. 

port.  A  junction  between  devices  through  which  data  flows.  An 
electrical  connection  between  your  computer  and  a  peripheral. 

position  independent  module.  A  module  that  need  not  be 
loaded  at  any  certain  location  in  memory. 

procedure.    A  program  or  routine  your  computer  can  execute. 

procedure  file.  A  file  containing  one  or  more  OS-9  commands. 
You  can  execute  a  procedure  file  in  the  same  manner  as  you  exe- 
cute OS-9  commands  or  programs. 

process.  A  computer  program  or  a  routine  that  performs  a 
specific  task  as  part  of  a  computer  program. 

process  descriptor.  A  block  of  data  that  includes  information 
about  a  process,  its  state,  memory  allocations,  priority,  queue 
pointers,  and  so  on. 

process  ID.  A  unique  number  the  system  gives  each  process  it 
executes. 
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process  priority.  A  value  you  or  the  system  gives  to  a  process 
that  determines  the  amount  of  CPU  (execution)  time  it  is  to 
receive  in  a  multi-tasking  environment. 

process  state.  The  condition  of  a  process  in  regard  to  its  exe- 
cution. A  process  can  be  active  (executing),  waiting  (awaiting  its 
turn  for  processing),  or  sleeping  (inactive  until  it  receives  a  sig- 
nal to  awaken). 

program.  Code  that  causes  your  computer  to  perform  some 
function  or  a  series  of  functions. 

program  modules.  Executable  code.  Modules  you  can  run  to 
perform  a  function  or  series  of  functions. 

public.  Any  user  of  a  program  or  module  other  than  the  owner. 
See  owner. 

purge.  Delete.  Usually  refers  to  removing  all,  or  a  selected 
group,  of  files  from  a  directory. 

RAM.  Random  access  memory.  Computer  memory  you  can 
write  to  (change)  and  read  from. 

RAM  disk.  A  portion  of  your  computer's  memory  that  OS-9 
can  use  for  data  storage  and  retrieval  in  the  same  manner  as  it 
uses  an  external  disk  drive.  However,  be  certain  you  copy  RAM 
disk  data  to  a  floppy  diskette  or  hard  disk  before  you  exit  OS-9 
or  turn  off  your  computer.  If  you  do  not,  the  data  is  lost. 

random  access.  Reading  (accessing)  information  in  a  block  of 
data  without  first  having  to  read  any  preceding  data. 

raw  data.  Unformatted  information  that  is  passed  to  a  device 
exactly  as  it  exists. 

RBF.  The  random  block  file  manager  that  processes  all  disk 
input/output. 

re-entrant  programs.  Programs  or  modules  that  can  be  used 
by  more  than  one  process  at  the  same  time. 

read.  The  process  of  transferring  data  from  a  device  into  the 
computer's  memory. 

read  permission.  System  permission  to  read  (withdraw  data 
from)  a  file. 
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read  data  type.  A  type  of  variable  that  can  store  floating 
point  numbers  in  the  range  ±  1  x  10-38. 

record.  A  collection  of  related  data  items  that  a  program  or 
process  considers  to  be  a  unit  for  the  purpose  of  processing.  A 
subdivision  of  a  file,  such  as  all  information  about  a  single  item 
in  an  inventory  file. 

record  locking.  Protecting  a  portion  of  a  file  to  ensure  that 
one  process  does  not  change  it  while  another  process  is  using  it. 

recursive  procedure  or  routine.  A  procedure  or  routine  that 
repeatedly  executes  itself  (that  contains  a  statement  causing  it 
to  run  itself  one  or  more  times). 

register.  A  location  within  a  computer's  memory  (often  in  the 
CPU)  for  storing  values  during  arithmetic,  logic,  or  transfer 
operations. 

remarks.  Text  contained  in  a  program  that  describes  the  pro- 
gram itself  and  that  is  not  to  be  executed. 

ROM.  Read  only  memory.  Computer  memory  containing  con- 
stant values  that  the  computer  can  read  but  cannot  change. 

ROOT  directory.  The  parent  directory  of  all  files  and  directo- 
ries on  a  disk.  The  ROOT  directory  is  created  by  FORMAT. 

run.    To  execute,  or  to  cause  a  program  or  procedure  to  start. 

runtime.    The  duration  of  a  program's  execution. 

SCF.  The  sequential  character  file  manager  that  handles  non- 
disk  input/output  operations  to  devices  such  as  printers  and 
terminals. 

scratched.  Destroyed.  When  you  copy  one  file  over  another  file, 
or  the  contents  of  one  disk  onto  another  disk,  any  data  existing 
in  the  second  file  or  on  the  second  disk  is  scratched. 

sector.  A  division  of  a  disk  track.  Disk  tracks  are  organized 
into  several  sectors. 

seek.  To  position  a  file  pointer  at  a  specific  byte  location  in  a 
file. 

semigraphics.  Graphics  (designs  on  the  display  screen)  using 
ASCII  graphic  characters. 
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sequential  access.  The  process  of  reading  data  in  order,  one 
character  at  a  time. 

sequential  execution.  Executing  a  series  of  commands  or  pro- 
cesses, one  after  the  other. 

sequential  file.  A  file  consisting  of  records  of  various  lengths 
that  must  be  accessed  one  after  the  other,  starting  at  the  first 
record. 

serial.  Refers  to  transmissions  in  which  data  leaves  or  arrives 
at  a  location  or  device,  with  data  units  following  one  after  the 
other  in  space  or  time. 

Setstat.  An  OS-9  routine  that  sets  (changes)  the  state  or  sta- 
tus of  a  specific  system  operation. 

shell.    The  command  interpreter. 

sibling.  One  of  two  or  more  processes  executed  by  the  same 
parent  process. 

sign  bit.  The  leftmost  bit  of  a  binary  number  that  serves  as  an 
indicator  to  show  whether  the  number  is  positive  or  negative. 
Normally,  a  value  of  0  indicates  positive,  and  a  1  indicates 
negative. 

signal.  An  interrupt  from  the  system  or  another  process  that 
changes  a  procedure's  or  a  device's  state.  For  example,  signals 
set  an  active  process  to  a  waiting  state,  awaken  an  inactive  or 
sleeping  process,  or  change  the  display  window. 

single  step.  A  procedure  in  the  Debug  mode  that  lets  you  exe- 
cute one  procedure  statement  and  (optionally)  view  the  results. 

single-user  file.  A  file  that  only  one  person  can  access  at  a 
time. 

single-user  module.  A  program  that  only  one  person  can  use 
at  a  time. 

sleeping  state.  A  situation  where  you  or  the  system  suspends 
a  process  for  a  specified  time  or  until  you  or  the  system  sends  it 
a  wakeup  signal. 

source  code.  Program  code  produced  using  a  computer  lan- 
guage. Before  it  can  control  a  computer,  source  code  must  be 
translated  into  machine  language,  either  by  a  compiler  or  a 
translator  program.  See  also  compiler. 
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stack.  A  storage  area  in  your  computer's  memory  in  which 
data  can  be  placed  or  recovered  in  sequence,  from  one  end  only. 

standard  error  path.  The  route  through  which  your  computer 
sends  error  codes  and  other  messages  to  the  screen. 

standard  input  path.  The  route  through  which  you  can  send 
data  to  your  computer  (usually  the  keyboard). 

standard  output  path.  The  route  your  computer  uses  to  send 
data  to  the  screen. 

start  up.     To  turn  on  your  computer  and  initialize  OS-9. 

stop  bits.  One  or  two  bits  that  a  terminal  program  sends  after 
each  unit  of  data  to  indicate  that  the  transmission  of  the  unit  is 
complete. 

string.    A  group  of  alphanumeric  characters. 

string  data  type.  A  type  of  variable  that  can  contain  one  or 
more  ASCII  values  (values  representing  alphanumeric  characters 
or  other  symbols).  String  data  types  can  be  any  length,  up  to  the 
capacity  of  your  computer's  memory. 

structured  programming.  Building  a  program  out  of  a  series 
of  procedures,  each  of  which  performs  a  specific  task  but  com- 
bines with  its  associated  procedures  as  one  program. 

subdirectory.  A  directory  that  resides  within  another  (parent) 
directory. 

subroutine.  An  operation  that  performs  a  specific  task  as  part 
of  a  larger  operation. 

super  user.  The  system  user  who  has  control  of  the  entire  sys- 
tem and  access  to  all  system  files  and  modules.  User  Number  0. 

symbolic  debugging.  An  error  correcting  system  that  lets  you 
pause  program  execution  and  view  the  current  values  of  vari- 
ables, using  their  program  names. 

syntax.  The  rules  for  forming  legal  instructions  for  your 
computer. 

system.  (1)  A  group  of  files  and  programs  that  provide  you 
with  control  over  your  computer.  (2)  Your  computer  with  all  its 
attached  devices. 
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system  call.  Built-in  OS-9  routines  that  perform  particular 
functions,  such  as  accessing  disk  files,  printing  data  on  the 
screen,  and  so  on. 

table.  A  storage  area  in  memory  or  on  disk  containing  ordered 
data  to  be  used  by  a  process  or  function. 

task.    A  unit  of  work  performed  by  your  computer. 

terminal.  A  computer  or  an  electronic  device,  with  a  screen 
and  keyboard,  connected  to  your  Color  Computer  3.  You  can 
access  OS-9  functions  from  a  terminal  in  the  same  manner  as 
you  can  access  them  from  your  Color  Computer  3  keyboard. 

text  files.  Files  containing  printable  characters,  or  the  code 
representing  such  characters. 

text  screen.  A  Type  1  or  2  screen.  Text  screens  use  hardware 
generation  of  characters  (fonts  are  not  definable)  and  are  often 
referred  to  as  hardware  screens  or  windows.  Text  screens  cannot 
display  graphics.  Text  operations  occur  faster  in  text  windows/ 
screens  than  on  graphic  windows/screens. 

text  window.     Any  window  created  on  a  hardware  text  screen. 

time  slice.  The  period  of  time  between  system  clock  ticks.  A 
tick  occurs  every  l/60th  of  a  second. 

timesharing.  A  situation  in  which  more  than  one  person  uses 
the  same  operating  system. 

token.  In  the  BASIC  language,  a  numeric  value  that  represents 
a  keyword. 

trace.  To  display  each  procedure  statement  as  it  executes  and 
view  its  results. 

tracks.  Magnetically  created  concentric  circles  created  on  a 
disk  for  the  storage  of  data.  Tracks  are  established  when  you  for- 
mat a  disk. 

transparent  characters.  Characters  that  display  over  screen 
images  without  erasing  any  of  the  area  surrounding  the 
characters. 

unlink.  To  remove  a  module  (program)  from  your  computer's 
memory. 

update  mode.  The  condition  of  a  file  when  it  is  open  for  both 
reading  and  writing. 
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user  ID.  A  number  that  identifies  the  operator  to  which  a  pro- 
cess belongs. 

user  number.    See  user  ID. 

utility.  A  short  program  that  performs  a  frequently  required 
task,  usually  for  the  maintenance  of  your  computer  system  or 
files. 

variable.  A  unit  of  storage  with  no  fixed  value.  You  define  a 
variable  and  locate  it  in  your  computer's  memory  using  a  vari- 
able name. 

VDG.    Video  Display  Graphics. 

vector.    A  graphics  line  or  portion  of  a  line. 

verify.     To  check  data  for  accuracy. 

wait  state.  A  situation  in  which  a  process  remains  suspended 
until  one  of  its  child  processes  terminates  or  until  it  receives  a 
wakeup  signal  from  the  system. 

wake  up.  To  continue  the  execution  of  a  process  that  has  been 
suspended. 

wild  card.  A  symbol  that  represents  or  takes  the  place  of  one 
or  more  other  characters  or  symbols. 

WINDINT.    Window  interface. 

window.  All  or  a  portion  of  your  video  screen  with  specific  for- 
mats (columns,  lines,  size,  colors,  and  so  on)  and  type  (graphics, 
text,  or  both).  An  area  of  a  screen  in  which  you  can  run  a  pro- 
cess or  which  can  receive  input. 

word  length.    The  number  of  bits  to  transmit  as  one  unit. 

workspace.  A  portion  of  your  computer's  memory  that 
BASIC09  establishes  for  the  storage  and  manipulation  of 
procedures. 

write.  To  transfer  data  from  the  computer's  memory  to  a 
device. 

write  permit.    System  permission  to  change  the  data  in  a  file. 

write  protect.  A  method  of  protecting  a  diskette  so  that  your 
computer  cannot  change  the  data  on  it. 
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